Docusaurus vs. Starlight: Warum wir für unsere technische Dokumentation den Wechsel vollzogen haben

Im Zeitalter moderner Softwareentwicklung gewinnt die Wahl des passenden Dokumentations-Frameworks zunehmend an Bedeutung. Technische Dokumentation steht heute im Fokus vieler Unternehmen, die ihre Produkte und Dienste klar, übersichtlich und effektiv kommunizieren möchten. Zwei der aktuell führenden statischen Site-Generatoren für Dokumentationen sind Docusaurus und Starlight. Im Rahmen unseres Projekts Distr bei Glasskube haben wir vor Kurzem von Docusaurus zu Starlight gewechselt. Dieser Schritt bot uns die Möglichkeit, beide Frameworks eingehend zu vergleichen, Vor- und Nachteile abzuwägen und daraus unsere Schlüsse für den Einsatz in modernen Entwickler- und Anwenderprojekten zu ziehen.

Docusaurus ist seit 2017 am Markt, entwickelt von Joel Marcey und mittlerweile ein bewährtes Open Source Framework, das sich auf React stützt. Durch seine lange Präsenz in der Entwickler-Community konnte es sich als solider Standard für technische Dokumentationsseiten etablieren. Starlight hingegen ist mit seiner ersten Version 2023 ein junges Framework, das auf Astro aufbaut. Astro ermöglicht die Nutzung mehrerer Frontend-Frameworks, darunter React, Vue und Svelte, und legt Wert auf Performance und Flexibilität. Eine der zentralen Anforderungen für unser Evaluation war das Design.

Docusaurus verwendet das CSS-Framework Infima, das sich zwar nahtlos integriert und einen modernen Look bietet, jedoch eng gekoppelt ist und wenig Raum für eigene Anpassungen lässt. Die fehlende Möglichkeit, bekannte Rahmen wie Tailwind oder Bootstrap nahtlos zu integrieren, schränkte uns ein. Starlight dagegen verzichtet auf ein eingebautes CSS-Framework und ermöglicht mit einer einzigen Befehlszeile die Integration von TailwindCSS, was uns eine deutlich flexiblere und individuelle Gestaltung zulässt. Dieser Aspekt war für uns essenziell, da eine moderne und ansprechende Dokumentation maßgeblich zur Nutzererfahrung beiträgt. Im Bereich SEO zeigen beide Frameworks solide Leistungen.

Sie erlauben das einfache Setzen von wichtigen Meta-Tags, Open Graph-Informationen und verfügen über ein automatisches Sitemap-Generierungsfeature, was für Sichtbarkeit und Auffindbarkeit in Suchmaschinen von Bedeutung ist. Während Docusaurus bereits über ein integratives Bildoptimierungssystem verfügt, zeigte sich die Implementierung hier als eher umständlich. Starlight punktet durch Plugins, die eine Bildkomprimierung und Optimierung vereinfachen. Die Tatsache, dass beide Frameworks statisch gerenderte Seiten erzeugen, führt zu extrem schnellen Ladezeiten – ein wichtiger Faktor für SEO und Nutzerzufriedenheit. Für Entwickler ist die Handhabung und das tägliche Arbeiten mit dem Framework entscheidend.

Docusaurus basiert direkt auf React und hat damit eine starke Abhängigkeit zu diesem Ökosystem. Updates bringen oft Kompatibilitätsherausforderungen mit sich, da neben dem Kern-Framework auch zahlreiche Plugins geprüft und angepasst werden müssen. Dies resultiert in einer vermeintlich höheren Wartungsbelastung. Starlight hingegen hängt allein von Astro ab, einem einheitlichen Ökosystem, das von einem kleinen Team entwickelt wird. Dies führt zu weniger Abhängigkeiten, einfacheren Updates und insgesamt einer geringeren Komplexität.

Ein bedeutsamer Punkt für uns war die Geschwindigkeit der Entwicklung und die Reaktionszeit des Entwicklungssystems. Bei Docusaurus kam es zeitweise zu vergleichsweise langen Startzeiten des Entwicklungsservers, was den Workflow störte. Mit Starlight reduzierten wir diese Wartezeiten erheblich, denn der auf Go basierende Astro-Compiler beschleunigt den Buildprozess deutlich. Schnelle Ladezeiten der Entwicklungsumgebung führen unweigerlich zu höherer Produktivität und besserer Motivation. Nicht unerwähnt bleiben darf die Frage nach der Erweiterbarkeit und Flexibilität.

Docusaurus bringt von Haus aus Beispiele für Marketing-Seiten und Blogs mit, was besonders für Projekte hilfreich ist, die neben der technischen Dokumentation auch klassische Webseiteninhalte pflegen möchten. Starlight hingegen ist stark auf Dokumentationszwecke fokussiert. Der Aufbau von Marketingseiten ist zwar möglich, erfordert allerdings Anpassungen und Umwege – wie bei uns die gezwungene Umleitung zu /docs –, die den Workflow verkomplizieren. Zudem fehlen bis dato wichtige Integrationen wie Mermaid für Diagramme, obwohl es entsprechende Nachfragen und Workarounds gibt. Die Strukturierung unserer technischen Dokumentation wurde ebenfalls maßgeblich beeinflusst.

Inspiriert von bekannten Projekten wie Flux und Docker strukturierten wir den Inhalt so, dass Nutzer mit einer Einführung starten, die grundlegende Konzepte erklärt, gefolgt von praxisnahen Anwendungsfällen und detaillierten Guides. Diese Navigation unterstützt eine theoretische, aber auch praktische Annäherung und erleichtert Einsteigern wie fortgeschrittenen Anwendern das Verständnis und den Zugriff. Ergänzende Dokumente für Selbsthosting, API-Nutzung, Automatisierung und Authentifizierung runden das Gesamtbild einer umfassenden Dokumentation ab. Wir beobachteten darüber hinaus mittels Analysewerkzeugen wie PostHog, dass Nutzer die Dokumentation oft linear und ähnlich dem Lesen eines Buches konsumieren. Dies unterstreicht die Bedeutung einer sehr gut durchdachten Reihenfolge der Inhalte – der erste Eindruck entscheidet darüber, ob Nutzer weiterziehen oder abbrechen.

Unsere Erfahrung zeigte, dass klare, prägnante und visuell unterstützte Texte besonders gut aufgenommen werden. Floskelreiche oder ausschweifende Erläuterungen hingegen schrecken ab. Die Kunst besteht darin, Informationen leicht verständlich, skimmbar und direkt anwendungsbezogen zu präsentieren. Der Umstieg von Docusaurus auf Starlight bedeutete für unser Team zwar eine Lernkurve, doch diese war angesichts der Vorteile durchaus überschaubar. Die moderne Optik, die deutlich verbesserte Entwicklererfahrung und schnellere Entwicklungszyklen waren für uns überzeugende Argumente.

Trotz kleinerer Einschränkungen, wie zum Beispiel fehlender nativer Marketing-Seiten-Unterstützung und noch nicht integrierter Mermaid-Unterstützung, sind wir mit der Entscheidung glücklich und werden Starlight künftig auch für weitere Projekte einsetzen. Die Entscheidung zwischen Docusaurus und Starlight hängt letztlich von individuellen Anforderungen ab. Wer eine ausgereifte Lösung mit vielen vorkonfigurierten Features sucht und Marketing-Seiten integrativ nutzen möchte, findet mit Docusaurus ein robustes Framework. Für Teams, die Flexibilität, Performance und modernes Design priorisieren, ist Starlight eine vielversprechende Wahl mit Zukunftspotential. Unser Fazit lässt sich zusammenfassen: Starlight ist eine moderne, performante und entwicklerfreundliche Lösung, die gerade für technische Dokumentationen glänzt, auch wenn sie aktuell noch in einigen Bereichen Nachholbedarf hat.

Der Umstieg machte uns experimentierfreudig und brachte uns weitere Erkenntnisse zum Aufbau und zur Struktur unserer Dokumentationsinhalte. So haben wir nicht nur eine hervorragende technische Basis geschaffen, sondern auch die Qualität unserer Dokumentation nachhaltig verbessert.