1.1 KiB
1.1 KiB
Dokumentation schreiben
Vor dem Schreiben
- Kläre, wer liest: Nutzer, Entwicklerinnen im Team, Betrieb. Jede Gruppe bekommt eigene Abschnitte, keine Mischung.
- Suche, wo das Thema schon steht. Eine Sache steht an genau einer Stelle; anderswo wird darauf verwiesen.
Beim Schreiben
- Erst das Ergebnis, dann der Weg: Was kann man danach, welcher Befehl, was kommt heraus.
- Jedes Beispiel muss so funktionieren, wie es dasteht. Befehle und Ausgaben vorher ausprobieren oder aus dem Code ableiten.
- Kurze Sätze, aktive Form, ein Gedanke pro Absatz. Tabellen für Vergleiche, Listen für Schritte.
- Fachbegriffe beim ersten Auftreten erklären oder auf das Glossar verweisen.
Kommentare im Code
Kommentare erklären das Warum, nicht das Was: Annahmen, Grenzen, Gründe für einen ungewöhnlichen Weg. Was der Code selbst sagt, kommt nicht in einen Kommentar.
Nach Code-Änderungen
Suche nach Namen von geänderten Befehlen, Optionen, Feldern und Fehlermeldungen in der Dokumentation und passe jede Fundstelle an. Nenne am Ende, welche Dateien du geändert hast und welche du geprüft, aber gelassen hast.