In der Welt der Softwareentwicklung sind gut strukturierte und leicht zugängliche Dokumentationen das Rückgrat erfolgreicher Produkte. Insbesondere für Entwickler, die sich schnell in neue Plattformen einarbeiten wollen, ist der erste Eindruck der Entwicklerdokumentation entscheidend. Im Mai 2025 haben wir deshalb unsere Entwicklerdocs umfassend überarbeitet, um Entwicklern eine wesentlich bessere Nutzererfahrung zu bieten und ihnen die Arbeit mit Trophy so einfach und intuitiv wie möglich zu machen. Die Wahl des passenden Dokumentationsanbieters war eine der wichtigsten Entscheidungen in diesem Prozess. Der Markt für Dokumentationslösungen wächst stetig, und es gibt zahlreiche Anbieter wie GitBook, Docusaurus, Hashnode, Fern oder Mintlify.
Während wir unsere SDKs mit Fern pflegen, entschieden wir uns für Mintlify als Plattform unserer Dokumentationsseite. Die Entscheidung beruhte vor allem auf Mintlifys hervorragender Schreibumgebung, der Möglichkeit, eigene React-Komponenten einzubinden und den vergleichsweise fairen Hosting-Kosten auf einem individuellen Domainnamen. Ein großer Vorteil war zudem, dass sowohl Fern als auch Mintlify auf derselben einzigen Datenquelle basieren: der OpenAPI-Spezifikation von Trophy. Wir empfehlen insbesondere die Nutzung des OpenAPI-Formats für API- oder SDK-Dokumentationen. Im Gegensatz zu proprietären Specs wie dem Fern-Format ist OpenAPI breit kompatibel und wird von allen gängigen Dokumentations-Dienstleistern unterstützt.
Dieses offene Format ermöglicht einen einfachen Wechsel des Anbieters, falls ein anderer Dienst in Zukunft überzeugender sein sollte. Wir selber haben von dieser Flexibilität profitiert, als wir unsere API-Dokumentation von Fern zu Mintlify migrierten. OpenAPI schafft damit eine wichtige Basis für nachhaltige und zukunftssichere Dokumentationsprojekte. Eine weitere wichtige Herausforderung war die Entscheidung für ein übersichtliches und benutzerfreundliches Navigationskonzept. Der Kern dabei war, die wichtigsten Inhalte für die Nutzer in möglichst wenigen Klicks erreichbar zu machen.
Ebenso wichtig war die einfache Zugänglichkeit zu weiteren nützlichen Ressourcen wie dem GitHub-Repository oder der Statusseite. Schließlich wollten wir klar zwischen den verschiedenen Dokumentationsarten unterscheiden: Plattform-Dokumente, API-Referenzen, Tutorials und Beispiele sollten sauber voneinander getrennt und gut auffindbar sein. Nach mehreren Tests verschiedener Modelle entschieden wir uns für eine tabbasierte Navigation. Die Tab-Leiste gliedert sich in Home, Guides und API Reference. Der Home-Tab ist die Startseite und soll grundlegende Fragen beantworten: Was ist Trophy? Welche Features bietet es? Und warum sollten Entwickler die Plattform nutzen? Im Guides-Tab stehen praktische Anleitungen im Vordergrund.
Hier finden Entwickler Hilfestellungen, wie sie bestimmte Funktionen umsetzen und welche Best Practices sie dabei berücksichtigen sollten. Der API Reference Tab stellt eine interaktive Umgebung dar, in der Entwickler die einzelnen Funktionen von Trophy erkunden, ausprobieren und detaillierte Informationen zu einzelnen Endpunkten erhalten können. Dieses differenzierte Menü trägt dazu bei, dass jeder Besucher schnell das passende Wissen für seinen individuellen Wissensstand und Bedarf findet. Gleich in allen Bereichen sind wichtige Links prominent platzieret. So finden sich Verweise zu unseren GitHub-Repositories, weiterführenden SDK-Dokumenten und zur Statusseite.
Für den Fall, dass Nutzer Unterstützung brauchen, steht ein schnell erreichbarer Mailto-Link bereit. Zudem gibt es auf jeder Seite am Ende einen Support-Bereich, der weitere Hilfen und Kontaktmöglichkeiten bietet. Neben der klaren Struktur war es uns zudem wichtig, die Dokumentation mit reichhaltigen Inhalten auszustatten. Hierbei setzten wir vor allem auf visuelle Elemente wie Flowchart-Diagramme. Bekanntermaßen vermittelt ein Bild als Erklärmedium oft mehr als lange Textpassagen, vor allem, wenn komplexe Zusammenhänge dargestellt werden sollen.
Mithilfe von Mermaid-Diagrammen integrierten wir erklärende Flussdiagramme, die zentrale Konzepte anschaulich und kompakt veranschaulichen. So können Entwickler Sachverhalte schneller erfassen und behalten sie länger im Gedächtnis. Darüber hinaus sind Code-Snippets ein unverzichtbarer Bestandteil einer modernen Entwicklerdokumentation. Wir haben darauf geachtet, dass für alle von uns unterstützten Programmiersprachen konkrete Beispielcodes bereitgestellt werden. Das erleichtert Entwicklern den Einstieg erheblich, denn sie können den passenden Code für ihre bevorzugte Sprache direkt übernehmen und an ihre individuellen Bedürfnisse anpassen.
Zusätzlich heben wir in den Snippets die relevanten Codeabschnitte hervor, die im begleitenden Text erläutert werden. Dadurch wird das Verständnis erleichtert und die Relevanz der gezeigten Beispiele verstärkt. Ein gutes Dokumentationssystem lebt zudem vom Feedback seiner Nutzer. Deshalb haben wir es den Besuchern einfach gemacht, uns Rückmeldungen zu einzelnen Seiten zu geben. Da unsere Dokumentation Open Source ist, können Entwickler auch direkt über GitHub Beiträge leisten, Korrekturen vorschlagen oder Probleme melden.
Dadurch schaffen wir eine lebendige und sich stetig verbessernde Wissensbasis, die genau auf die Bedürfnisse unserer Nutzer zugeschnitten ist. Die Arbeit an unserer Dokumentation ist jedoch noch lange nicht abgeschlossen. Unser Fahrplan sieht weitere spannende Features vor. Ein zentraler Punkt ist die Personalisierung der Inhalte. Wenn Nutzer bereits in ihrem Trophy-Konto angemeldet sind, wollen wir künftig automatisch Codebeispiele und Schnittstellen mit ihren API-Schlüsseln und bevorzugten Programmiersprachen anpassen – ähnlich wie es bekannte Anbieter wie Stripe vormachen.
So wird die Entwicklererfahrung maßgeblich vereinfacht. Ein weiteres Ziel ist es, unsere Dokumentation noch mehrsprachig anzubieten, um für Entwickler aus aller Welt besser zugänglich zu sein. Gerade die Unterstützung von weiteren Sprachen kann die Reichweite und Akzeptanz unserer Plattform signifikant verbessern und nicht-native Englischsprecher besser bedienen. Ebenso planen wir, moderne KI-Technologien, insbesondere Large Language Models (LLMs), in unsere Docs zu integrieren. Damit könnten Nutzer beispielsweise Fragen direkt in der Dokumentation stellen und unmittelbar relevante Antworten erhalten, anstatt endlos in Texten zu suchen.
Der gesamte Prozess des Updates hat knapp eine Woche gedauert – eine erstaunlich kurze Zeitspanne, wenn man die Qualität und Benutzerfreundlichkeit der neuen Docs berücksichtigt. Das Ergebnis erfüllt unsere Erwartungen und wir sind zuversichtlich, dass die Entwicklergemeinde dadurch besser unterstützt wird. Wer mehr erfahren möchte oder Interesse hat, selbst eine solche Dokumentationsseite aufzubauen, darf sich jederzeit gern mit uns in Verbindung setzen. Mit gezieltem Einsatz moderner Tools, einem bedachten Layout und reichhaltigen Inhalten haben wir eine Entwicklerdokumentation geschaffen, die nicht nur informiert, sondern auch inspiriert und den Entwicklungsprozess wirkungsvoll unterstützt. Das macht Trophy Docs zu einer zentralen Ressource, auf die Entwickler vertrauen können, wenn sie neue Funktionen entdecken oder Probleme lösen möchten.
Die Zukunft der Entwicklerdokumentation wird dynamischer, interaktiver und persönlicher – und wir freuen uns darauf, diesen Weg mit unseren Nutzern gemeinsam zu gehen.
