Dokumentation, die nicht veraltet: was man beschreibt und was man ableitet
Die Dokumentation ist von 2011. Sie beschreibt ein System, das es so nicht mehr gibt. Dieser Satz fällt in fast jedem Erstgespräch, und die übliche Reaktion — eine neue Dokumentation schreiben — erzeugt in drei Jahren dasselbe Problem.
Handgepflegte Systemdokumentation veraltet strukturell, weil ihre Pflege mit dringenderer Arbeit konkurriert. Die Lösung ist eine Trennung: Alles Ableitbare — Abhängigkeiten, Schnittstellenverträge, Datenmodelle, Aufrufketten — wird erzeugt statt beschrieben. Beschrieben wird nur, was nicht im System steht: eine Entscheidungsliste mit Begründungen und verworfenen Alternativen, dokumentierte Warnungen aus früheren Fehlversuchen, die offenen Punkte und die Zuordnung von Fachbereichen zu Systembereichen. Abgelegt wird alles neben dem Code, nicht im Wiki.
Warum handgepflegte Dokumentation veraltet
Nicht aus Nachlässigkeit, sondern strukturell: Sie beschreibt einen Zustand, der sich ändert, und die Pflege konkurriert mit Arbeit, die dringender aussieht. Nach jeder Änderung müsste jemand daran denken. Bei erhöhtem Änderungsvolumen ist dieser Mechanismus endgültig nicht mehr tragfähig.
Die Trennung, die den Unterschied macht
Alles, was sich aus dem System ableiten lässt, wird abgeleitet — nicht beschrieben. Abhängigkeiten, Schnittstellenverträge, Datenmodelle, Aufrufketten, Konfigurationen: Diese Dinge stehen im System und lassen sich erzeugen. Beschrieben wird nur, was nicht im System steht: Begründungen, Entscheidungen, Warnungen und offene Punkte.
Die vier Dokumente, die tatsächlich gebraucht werden
Erstens eine Entscheidungsliste: Was wurde wann entschieden, mit welcher Begründung und welchen verworfenen Alternativen. Zweitens die Warnungen: Welche Änderungen sind schon einmal schiefgegangen und warum. Drittens die offenen Punkte: Was wir nicht klären konnten. Viertens die Zuordnung von Fachbereichen zu Systembereichen — wer ruft an, wenn was nicht geht.
Warum die offenen Punkte das wichtigste Dokument sind
Weil sie den nächsten Menschen davor bewahren, Nichtwissen für Wissen zu halten. Eine Dokumentation ohne diesen Teil suggeriert Vollständigkeit, und genau diese Suggestion ist der Grund, warum eine alte Dokumentation gefährlicher ist als keine.
Wo die Dokumentation liegt
Neben dem Code, im selben Repository, mit derselben Versionierung. Nicht in einem Wiki, das eine eigene Berechtigungsstruktur, eine eigene Suche und einen eigenen Verfallsmechanismus hat. Was neben dem Code liegt, wird bei einer Änderung gesehen — und das ist der einzige Mechanismus, der in der Praxis funktioniert.
Häufige Fragen
Wie erzeugt man Dokumentation automatisch?
Aus den Quellen, aus denen sie stammt: Abhängigkeitsgraphen aus Code und Konfiguration, Schnittstellenbeschreibungen aus den Verträgen, Datenmodelle aus dem Schema. Der Aufwand liegt einmalig bei der Einrichtung; danach ist der Stand immer aktuell, weil er beim Build entsteht.
Was ist mit vorhandener alter Dokumentation?
Nicht wegwerfen, aber datieren und als historisch kennzeichnen. Sie enthält oft Begründungen, die nirgends sonst stehen — und genau diese Begründungen sind der wertvolle Teil. Die Zustandsbeschreibungen darin sind wertlos und sollten als solche markiert sein.
Gehört Dokumentation ins Wiki oder ins Repository?
Ins Repository, wenn sie den Code betrifft. Ein Wiki hat eine eigene Suche, eigene Rechte und keinen Bezug zu einer Änderung. Was neben dem Code liegt, wird bei jeder Änderung gesehen und im Review mitgeprüft.
Wie ausführlich muss eine Entscheidungsliste sein?
Kurz. Je Entscheidung reichen Datum, Kontext, Entscheidung, verworfene Alternativen und Konsequenz — eine halbe Seite. Ausführlichkeit senkt die Wahrscheinlichkeit, dass sie geschrieben wird, und die Kürze macht sie später lesbar.
Rechnen Sie es für Ihre Organisation durch.
Vierzehn Angaben, fünf Minuten: Prüflücke, Legacy-Risiko und die Reihenfolge.
Engineering-Check starten →
