Fehlende, unstrukturierte oder veraltete Dokumentation endet immer gleich: Entwickler fragen Kollegen statt zu lesen.
Das DoD-Prinzip fuer Dokumentation
Jede neue Funktion, jedes neue Modul, jede neue API gilt ohne Dokumentation als nicht fertig, das Definition-of-Done-Prinzip auf Dokumentation angewendet. Klingt streng, ist aber der einzige verlaessliche Weg, Dokumentationsschulden zu vermeiden.
Was dokumentiert werden sollte
Zwingend gehoeren Architecture Decision Records fuer wichtige Entscheidungen, ein README mit Quickstart und Local-Setup, sowie API-Dokumentation ueber OpenAPI oder Storybook dazu. Sinnvoll sind zusaetzlich der Deployment-Prozess, Incident-Runbooks und ein Onboarding-Guide fuer neue Entwickler. Nicht noetig ist die Dokumentation jeder einzelnen Funktion oder selbsterklaerender, gut benannter Logik.
Living Documentation
Dokumentation muss nah am Code leben: ADRs im Repository, eine aus dem Code generierte OpenAPI-Spec, Storybook als Teil des Frontend-Projekts. Was ausserhalb des Repos lebt, wird zuverlaessig vergessen.
Templates senken die Huerde
Ein leeres Blatt ist der groesste Feind guter Dokumentation. Vorlagen fuer ADRs, READMEs und Runbooks machen den Einstieg deutlich leichter.
Checkliste: README mit Local-Setup-Anleitung vorhanden, ADRs fuer wichtige Architekturentscheidungen angelegt, API-Dokumentation aktuell, Dokumentation als Teil des DoD integriert, Onboarding-Guide vorhanden, Dokumentation im Repository statt in externem Wiki.
Ein Beispiel aus der Praxis
Ein neuer Entwickler brauchte fuer das lokale Setup eines Projekts ueber zwei Tage, weil die Installationsanleitung veraltet war und mehrere inzwischen entfernte Schritte enthielt. Nach der Ueberarbeitung des READMEs, verifiziert durch einen weiteren neuen Mitarbeitenden, der die Anleitung Schritt fuer Schritt nachvollzog, sank die durchschnittliche Onboarding-Zeit auf einen halben Tag. Der einfache Trick dahinter: Eine Dokumentation gilt erst als fertig, wenn sie tatsaechlich von jemand anderem erfolgreich befolgt wurde, nicht wenn der Autor sie fuer vollstaendig haelt.
Dokumentationsstruktur fuer euer Projekt? markom.digital hilft bei der Einfuehrung pragmatischer Dokumentationsstandards, ohne Overhead, mit echtem Nutzen.
