Dokumentation, die niemand liest, ist nutzlos. So schreiben Sie die nützliche Art.
Arten von Dokumentation¶
- Tutorial — lehrt (Schritt für Schritt)
- How-to Guide — löst ein Problem
- Referenz — technisches Detail
- Erklärung — erklärt Konzepte
Prinzipien¶
- Schreiben Sie für den Leser, nicht für sich selbst
- Konkrete Beispiele > abstrakte Erklärungen
- Kurze Sätze, kurze Absätze
- Code, der funktioniert (kein Pseudocode)
- Halten Sie sie aktuell — veraltete Dokumentation ist schlimmer als keine
Struktur¶
- Warum — Motivation und Kontext
- Was — was es tut / löst
- Wie — Schritt für Schritt mit Beispielen
- Referenz — API, Konfiguration, Parameter
- Troubleshooting — bekannte Probleme
Werkzeuge¶
- Markdown + Git — einfach, versioniert
- MkDocs / Docusaurus — Static Site Generatoren
- Notion / Confluence — für interne Docs
- OpenAPI/Swagger — für API-Dokumentation
Docs as Code¶
Versionieren Sie Ihre Dokumentation in Git neben dem Code. Review in PRs. CI/CD für die Veröffentlichung. Code und Docs entwickeln sich gemeinsam.
Test¶
Geben Sie die Docs einem neuen Entwickler. Kann er damit loslegen? Wenn nicht, verbessern Sie sie.
Dokumentationwritingbest practices