Dokumentation, die Menschen wirklich lesen
Vier Dokumente, die genügen
Eine Einführungsdatei. Was es ist, wie man es lokal ausführt, wie man die Tests ausführt und wen man fragt. Sie muss genau sein — es ist das bei jeder Einarbeitung geprüfte Dokument.
Architekturentscheidungen. Eine Seite je bedeutsamer Entscheidung: Kontext, Optionen, was gewählt wurde und warum. Kurz und datiert.
Betrieb. Was zu tun ist, wenn etwas bricht, wie man deployt, wie man zurückrollt.
Schnittstelle. Aus dem Code, damit sie nicht altert.
Wie man sie frisch hält
Dokumentation, die nahe am Code lebt und in derselben Merge-Anfrage aktualisiert wird. Ein Dokument anderswo altert binnen zwei Monaten, und schlimmer — bleibt maßgeblich aussehend.
Was man nicht dokumentiert
Was der Code klar sagt. Ein Kommentar, der eine Zeile beschreibt, ist überflüssig; ein Kommentar, der erklärt, warum ein ungewöhnlicher Ansatz gewählt wurde, ist Gold wert.
Im Detail
Prüfen Sie die Einführungsdatei bei jeder Einarbeitung: Lassen Sie einen Neuling ihr wörtlich folgen und jede Stelle notieren, an der er stockte. Das ist der einzige Weg, die stillen Annahmen zu finden, die alle Erfahrenen im Kopf halten und niemand aufschrieb.