30 lines
1.1 KiB
Markdown
30 lines
1.1 KiB
Markdown
# Dokumentation schreiben
|
|
|
|
## Vor dem Schreiben
|
|
|
|
1. Kläre, wer liest: Nutzer, Entwicklerinnen im Team, Betrieb. Jede Gruppe
|
|
bekommt eigene Abschnitte, keine Mischung.
|
|
2. 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.
|