Dokumentation, die genutzt wird: Templates & DoD.
Entwickler-Dokumentation, die wirklich genutzt wird
Die beste Dokumentation ist die, die jemand liest. Nicht die, die am ausführlichsten ist.
Warum Dokumentation meistens scheitert
Entweder: Es gibt keine. Oder: Es gibt so viel, dass niemand weiß, wo er anfangen soll. Oder: Die Doku ist veraltet, weil niemand sie aktualisiert, wenn sich etwas ändert.
Alle drei Szenarien enden gleich: Entwickler fragen Kollegen statt zu lesen.
Das DoD-Prinzip für Dokumentation
Jede neue Funktion, jedes neue Modul, jede neue API – ohne Dokumentation gilt sie als "nicht fertig". Das ist das Definition-of-Done-Prinzip auf Dokumentation angewendet. Klingt streng, ist aber der einzige Weg, Dokumentationsschuld zu vermeiden.
Was dokumentiert werden sollte
Muss: Architecture Decision Records (ADRs) für wichtige Entscheidungen. README mit Quickstart und Local-Setup. API-Dokumentation (OpenAPI für REST, Storybook für UI-Komponenten).
Sollte: Deployment-Prozess. Incident-Runbooks. Onboarding-Guide für neue Entwickler.
Muss nicht: Jede einzelne Funktion (dafür ist der Code da). Selbsterklärende Logik, die gut benannt ist.
Living Documentation
Dokumentation muss nah am Code leben. ADRs im Repo. OpenAPI-Spec aus Code generiert. Storybook als Teil des Frontend-Projekts. Was außerhalb des Repos lebt, wird vergessen zu aktualisieren.
Templates helfen
Leeres Blatt ist der Feind von Dokumentation. Templates für ADRs, READMEs, Runbooks – damit senkt man die Hürde enorm.
Checkliste Entwickler-Dokumentation
README mit Local-Setup-Anleitung vorhanden
ADRs für wichtige Architekturentscheidungen angelegt
API-Dokumentation (OpenAPI) up-to-date
Dokumentation als DoD in Entwicklungsprozess integriert
Onboarding-Guide für neue Teammitglieder vorhanden
Dokumentation im Repo (nicht in externem Wiki, das veraltet)
Dokumentationsstruktur für euer Projekt?
markom.digital hilft bei der Einführung pragmatischer Dokumentationsstandards – ohne Overhead, mit echtem Nutzen.
