Behandeln Sie Dokumentation als Teil der Änderung
Wenn sich Verhalten ändert, ist der zuverlässigste Zeitpunkt für die Aktualisierung der Dokumentation derselbe Pull Request. Reviewer können Implementierung und Erklärung gemeinsam vergleichen, und Versions-Tags halten die Dokumentation auf dem Stand des veröffentlichten Codes.
- Halten Sie ein fokussiertes README in der Nähe der Komponente, die es erklärt.
- Verlangen Sie Dokumentations-Updates, wenn sich öffentliches Verhalten, Konfiguration oder Betriebsschritte ändern.
- Nutzen Sie Link- und Stilprüfungen in der Continuous Integration.
- Weisen Sie klare Verantwortlichkeit für risikoreiche Runbooks und Referenzseiten zu.
Wählen Sie den Dokumenttyp, bevor Sie schreiben
Ein Tutorial vermittelt Wissen durch eine Abfolge von Schritten. Eine How-to-Anleitung löst eine Aufgabe. Referenzmaterial beschreibt exaktes Verhalten. Eine Erklärung liefert Kontext und Abwägungen. Wenn alle vier in ein einziges langes README gemischt werden, wird jedes einzelne schwerer nutzbar.
Architektur-Entscheidungsprotokolle (ADR) sind ein weiteres nützliches Muster: Halten Sie Kontext, Entscheidung, Alternativen und Konsequenzen fest, solange die Überlegungen noch frisch sind. Markdown hält das Protokoll nahe am Code, ohne dass ein separater Publishing-Workflow nötig ist.
Machen Sie Codebeispiele testbar und ehrlich
Leser kopieren Beispiele. Nehmen Sie benötigte Imports, realistische Namen, erwartete Ausgabe und den relevanten Fehlerpfad auf. Wenn das Snippet bewusst unvollständig ist, sagen Sie das. Ein kleines getestetes Beispiel ist wertvoller als ein großer Block, der nur plausibel aussieht.
```bash # Validate docs before opening a pull request npm run lint npm run typecheck ``` Expected result: both commands exit with status 0.
Optimieren Sie für reviewbare Diffs
Verwenden Sie einen Satz pro Zeile nur, wenn das Repository diese Konvention durchgängig übernimmt; andernfalls brechen Sie natürlich um und überlassen Sie die Darstellung den Werkzeugen. Vermeiden Sie es, eine ganze Datei bei einer inhaltlichen Änderung neu zu formatieren. Stabile Überschriften und Referenzlinks erleichtern es, große Dokumente ohne unübersichtliche Diffs zu ändern.
- Vergeben Sie spezifische Überschriftennamen, die auch in generierten Ankern nützlich bleiben.
- Halten Sie Tabellen schmal und vermeiden Sie Zellen mit viel Fließtext.
- Verwenden Sie relative Links für Dateien, die mit dem Repository mitwandern.
- Fügen Sie keine Geheimnisse, privaten Logs oder ungeschwärzte Produktionsdaten in Beispiele ein.
Nutzen Sie Konvertierung als Ausgangspunkt für eine Migration
Eine Word-Datei, Tabellenkalkulation, ein PDF oder ein Foliensatz kann wertvolles Wissen enthalten, das noch nicht in einen Docs-as-Code-Workflow passt. Die Konvertierung zu Markdown entfernt einen Großteil der Präsentationsebene, aber ein Entwickler muss weiterhin Überschriften normalisieren, Links reparieren, Dateigrenzen wählen und die technische Richtigkeit bestätigen.
Behalten Sie das Quelldokument, bis die konvertierte Version reviewt wurde. Bei berechneten Daten oder signierten Aufzeichnungen kann das Original auch dann die maßgebliche Quelle bleiben, wenn eine lesbare Markdown-Sicherung zum Repository hinzugefügt wurde.