Handwerk, Qualität & Teams · Gemischt

Dokumentation, die Menschen wirklich lesen

In einem Satz: Dokumentieren Sie, was sich aus dem Code nicht ableiten lässt: Entscheidungen, Grenzen und den Weg zum Anfangen — alles andere altert und führt in die Irre.

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.

DokumentationProzess & Teams