Dokumentations-Frameworks

Das Konzept der Dokumentation

Der einfachste Ansatz für eine gute Dokumentation beginnt schon bei der Namenswahl für Klassen, Funktionen und Variablen, dem sogenannten selbstdokumentierenden Code. Durch die Wahl beschreibender Namen erhöht sich die Les- und Wartbarkeit des Codes schon ungemein. Dies erfordert jedoch weiterhin ein grundlegendes Verständnis des Programmcodes, das durch Kommentare erweitert werden kann.

Die nächste Stufe sind Signaturen von Funktionen und Klassen. Sie erlauben es auch, ohne den vollständigen Code zu lesen, zu verstehen, was eine Funktion oder Klasse tut und welche Werte sie erwartet und zurückgibt. Dank moderner LLMs (Large Language Models) können Signaturen aus fertigen Funktionen leicht abgeleitet werden, was wertvolle Informationen in kürzester Zeit liefert, die meist keine bis leichte Anpassungen benötigen.

Die wichtigste Art der Dokumentation ist die Schnittstellendokumentation. Sie beschreibt im Wesentlichen alle Signaturen, die von außen genutzt werden können. Wenn die Software mit einer anderen Software interagieren soll, ist diese Dokumentation unverzichtbar, da sie die nötige Abstraktion bietet, um mit der Software zu arbeiten, ohne sie im Detail kennen zu müssen. Zusätzlich lassen sich durch die Dokumentation auch andere wichtige Informationen vermitteln. Leider fehlen oft die Motivation, die Zeit oder das Geld für eine ausführliche Schnittstellendokumentation.

Zwischenformat

Anstatt die Dokumentation mühsam von Hand zu erstellen oder zu aktualisieren, können Tools diesen Prozess automatisieren. Solange der Code über grundlegende Signaturen verfügt, können Tools die Information auslesen und in ein lesbares Format überführen. Die beliebtesten Formate hierfür sind Markdown und AsciiDocs, da sie umfangreiche Formatierungsoptionen mit einer einfachen Syntax bieten. Die Tools zur Erzeugung dieser Zwischenformate hängen zwar von der Umgebung, der Programmiersprache und persönlichen Präferenzen ab, funktionieren aber überwiegend nach dem gleichen Prinzip.

Frameworks

Markdown- oder AsciiDocs-Dateien sind an sich schon nützlich, aber für eine vollständige Lösung fehlt noch eine Möglichkeit, die Dokumentation zugänglich zu machen. Hier kommen Static-Site-Generatoren (SSG) ins Spiel. Sie nehmen die einzelnen Markdown-Dateien und setzen die zu einer statischen Webseite zusammen (kompilieren). Dadurch kann die Dokumentation schnell geladen werden, verbraucht minimale Ressourcen und bleibt trotzdem voll funktionsfähig.

Docusuarus: Der Platzhirsch

Docusaurus ist der etablierte Marktführer in diesem Bereich. Das von Meta entwickelte Framework ist robust, zuverlässig und bekannt für seine Stabilität sowie ein umfangreiches Ökosystem.

\n
• Versionsverwaltung: Das Framework zeichnet sich durch seine Versionsverwaltung als Kernfunktion aus. Sie ermöglicht es, alte Dokumentationen weiterhin bereitzustellen, was den Support für ältere Softwareversionen erheblich vereinfacht.
\n
• Plugins: Docusaurus lässt sich durch eine große Anzahl von Plugins leicht in seiner Funktion erweitern.
\n
• React-basiert: Das Framework basiert auf React, wodurch sich bestehende React-Komponenten nahtlos in die Dokumentation integrieren lassen.
\n
• Bekanntheit: Durch seine Bekanntheit lassen sich einfach Informationen und Support finden

Fazit: Docusaurus macht seinem Namen alle Ehre und bietet ein starkes, erweiterbares, skalierbares und stabiles Ökosystem, das sich ideal für komplexe Projekte eignet.

Astro Starlight: Die moderne und performante Lösung

⚠️ Astro Starlight ist ein noch recht junges Framework, das dank seiner Flexibilität und Performance schnell an Popularität gewinnt.

Merkmale

• Performance: Starlight baut auf dem Astro-Framework auf, das nur minimalistisches JavaScript ausliefert. Dies führt zu schnellen Ladezeiten und einer besseren Nutzererfahrung, selbst bei sehr großen Dokumentationsseiten.
\n
• Flexibilität: Starlight ist 'Framework-agnostisch', was bedeutet, dass es nicht an eines der gängigen JS-Frameworks gebunden ist und maximale Freiheit bei der Gestaltung der Dokumentation bietet.
\n
• Plugins: Starlight besitzt (noch) nicht die gleiche Menge an Plugins wie Docusaurus, aber die Zahl wächst durch die Community und offizielle Plugins stetiig

"Fazit: Starlight ist ein junges, schnell wachsendes Framework, das sich besonders gut für moderne, flexible und performante Dokumentationsseiten eignet."

Anwendung im Entwickleralltag

Unabhängig von der Framework-Wahl kann die Dokumentation über CI/CD-Pipelines vollständig automatisiert bei jedem Deployment erstellt werden. Zusätzlich können manuell erstellte Dokumente und ein benutzerdefiniertes Design integriert werden, um eine passende Lösung zu schaffen.

Der eigentliche Prozess variiert je nach Anwendungsfall, lässt sich aber in wenigen, einfachen Schritten generalisieren:

\n
1. Zuerst werden Signaturen und ausgewählte manuelle Dokumentationen erstellt.
\n
2. Diese Informationen werden in ein Zwischenformat (meist Markdown) überführt.
\n
3. Das Zwischenformat wird mit den Stylingvorgaben zu einer statischen Webseite 'kompiliert'.
\n
4. Zuletzt wird die Webseite bereitgestellt.

Dieser Prozess kann durch die in den Frameworks enthaltenen Funktionen weitgehend automatisiert werden.