Beginne mit Content, nicht mit Screenshots
Eine beeindruckende Demo kann für deine Dokumentation trotzdem falsch sein. Schreibe zuerst auf, was publiziert werden muss: lange Manuals, API Reference, Tutorials, generierte Seiten, Versionen, mehrere Sprachen, Tausende Artikel oder eine Mischung.
Beschreibe danach, wer schreibt. Engineers, die täglich Markdown in Git bearbeiten, haben andere Bedürfnisse als gelegentliche Subject-Matter Experts im Browser.
Vergleiche das Content Model
Sphinx ist stark bei Cross-References, strukturierten Directives, langen technischen Dokumenten und Erweiterbarkeit. MkDocs passt gut zu Markdown-first und überschaubaren Strukturen. Astro ist ein breiteres content-focused Web Framework mit typed Content Collections, Assets, Routing und flexiblen Layouts; dafür besitzt das Team auch mehr vom Publishing-Produkt selbst.
Es geht nicht um einen Sieger, sondern um die passende Abstraktion.
Berechne die Wartungsfläche
Zähle Custom Plugins, Theme Overrides, Build Steps und interne Konventionen. Jede Anpassung wird beim nächsten Upgrade Arbeit erzeugen. Frage nicht nur „Können wir das anpassen?“, sondern „Versteht der nächste Maintainer warum?“.
Prototypisiere die schwierigen Fälle
Baue einen Spike mit großer Tabelle, Reuse, Lokalisierung, Code, Bildern, Redirects, Search-Metadaten und einer langen Seite. Teste mit repräsentativem Umfang.
Bewerte nicht nur die Homepage.
Erhalte einen Migrationsweg
Trenne Content-Semantik möglichst von Theme-spezifischem Markup. Bevorzuge normales Markdown und klar definierte Components gegenüber vielen Ad-hoc-HTML-Fragmenten. Dokumentiere das Metadaten-Schema.
Ein Generator ist Infrastruktur, nicht Identität. Wähle ihn so, dass Publishing heute zuverlässig und ein Wechsel morgen möglich bleibt.
Praxisbeispiel
Behandle „Einen Dokumentationsgenerator wählen, ohne eine Religion zu wählen“ als kleine Evaluation und nicht als Feature-Liste. Wähle drei echte Inhalte: eine einfache Seite, eine Seite mit Code oder strukturierten Daten und eine schwierige Seite mit Navigation, Wiederverwendung oder Lokalisierung. Teste alle drei und notiere, was leichter wird und welche neue Wartungslast entsteht.
Bewerte wiederkehrende Arbeit:
- versteht ein Autor die Quelle;
- sieht ein Reviewer einen sinnvollen Diff;
- weist ein Build-Fehler auf ein lösbares Problem hin;
- lässt sich Inhalt ohne manuelle Bereinigung verschieben, lokalisieren oder wiederverwenden.
Ein gutes Werkzeug reduziert Unsicherheit beim Schreiben, Review und Publizieren. Wenn Komplexität nur in fragile Konfiguration, Plugins oder das Wissen einer Person verschoben wird, gehört auch das in die Entscheidung.
Kurzer Redaktionscheck
- Beginne mit Content, nicht mit Screenshots. Eine beeindruckende Demo kann für deine Dokumentation trotzdem falsch sein.
- Vergleiche das Content Model. Sphinx ist stark bei Cross-References, strukturierten Directives, langen technischen Dokumenten und Erweiterbarkeit.
- Berechne die Wartungsfläche. Zähle Custom Plugins, Theme Overrides, Build Steps und interne Konventionen.
- Prototypisiere die schwierigen Fälle. Baue einen Spike mit großer Tabelle, Reuse, Lokalisierung, Code, Bildern, Redirects, Search-Metadaten und einer langen Seite.
