Technische Dokumentation, die nicht hinterherhinkt: erzeugen statt pflegen
Dokumentation war schon immer hinterher. Der Unterschied ist der Abstand: Was früher um Wochen veraltete, veraltet jetzt um Tage. Der übliche Ausweg — mehr Disziplin — funktioniert nicht, weil er mit jeder Änderung neu aufgebracht werden muss.
Bei hohem Änderungsvolumen ist handgepflegte technische Dokumentation nicht mehr aktuell zu halten. Die Trennung: Schnittstellen, Datenmodelle, Konfigurationen, Abhängigkeiten und Modulgrenzen werden aus dem Code erzeugt; geschrieben werden nur Begründungen, verworfene Alternativen, Fallstricke und Zuständigkeiten. Modelle helfen beim Erzeugen von Beschreibungen, nicht beim Warum — dort liefern sie plausible Erfindungen. Ein Gate im Build, das erzeugte gegen eingecheckte Beschreibung vergleicht, macht Aktualität zur Bedingung statt zum Vorsatz.
Die Trennung: ableitbar oder nicht
Alles, was im Code steht, gehört nicht in ein Dokument. Schnittstellenbeschreibungen, Datenmodelle, Konfigurationsoptionen, Abhängigkeiten, Modulgrenzen: erzeugbar, und damit immer aktuell. Was nicht im Code steht, muss geschrieben werden: Begründungen, verworfene Alternativen, bekannte Fallstricke, Zuständigkeiten. Diese zweite Gruppe ist klein und ändert sich selten — genau deshalb ist sie pflegbar.
Wo Modelle helfen und wo nicht
Sie helfen beim Erzeugen von Beschreibungen aus vorhandenem Code — eine Zusammenfassung je Modul, eine Erklärung einer komplexen Funktion, ein erster Entwurf einer Schnittstellenbeschreibung. Sie helfen nicht bei der Begründung, weil die nicht im Code steht. Wer ein Modell nach dem Warum fragt, bekommt eine plausible Erfindung — und die ist schlimmer als eine Lücke, weil sie glaubwürdig aussieht.
Der Mechanismus, der funktioniert
Dokumentation liegt neben dem Code, wird mit ihm versioniert und im selben Vorgang geprüft. Für die ableitbaren Teile läuft ein Gate: Weicht die erzeugte Beschreibung von der eingecheckten ab, schlägt der Build fehl. Damit ist Aktualität kein Vorsatz mehr, sondern eine Bedingung.
Die eine Datei, die den größten Unterschied macht
Eine kurze Entscheidungsliste je Bereich: Datum, Kontext, Entscheidung, verworfene Alternativen, Konsequenz. Eine halbe Seite je Eintrag. Sie beantwortet die Frage, an der neue Menschen und Modelle gleichermaßen scheitern — warum ist das so — und sie veraltet nicht, weil sie Vergangenheit beschreibt statt Zustand.
Was man weglassen sollte
Beschreibungen von Oberflächen, Aufzählungen von Klassen, Schritt-für-Schritt-Anleitungen für Dinge, die sich ändern. Diese Texte sind bei Erstellung schon halb falsch und binden Pflegeaufwand, der anderswo fehlt. Was oft gebraucht wird und sich ändert, gehört in ein erzeugtes Format oder gar nicht dokumentiert.
Häufige Fragen
Welche Dokumentation lässt sich automatisch erzeugen?
Schnittstellenbeschreibungen aus Verträgen oder Annotationen, Datenmodelle aus dem Schema, Abhängigkeitsgraphen aus Code und Konfiguration, Konfigurationsoptionen aus dem Quelltext. Als Faustregel: Alles, was einen Zustand beschreibt, sollte erzeugt werden.
Kann ein Modell Dokumentation schreiben?
Beschreibungen ja, Begründungen nein. Eine maschinell erzeugte Zusammenfassung eines Moduls ist ein guter Entwurf und sollte geprüft werden; eine maschinell erzeugte Begründung ist eine Erfindung, weil das Warum nicht im Code steht.
Wie erzwingt man Aktualität?
Über ein Gate: Die Beschreibung wird beim Build erzeugt und mit der eingecheckten verglichen. Bei Abweichung schlägt der Build fehl. Das klingt streng und ist der einzige Mechanismus, der ohne Disziplin auskommt.
Was ist der größte Hebel bei knapper Zeit?
Eine kurze Entscheidungsliste je Bereich mit Datum, Kontext, Entscheidung, verworfenen Alternativen und Konsequenz. Sie beantwortet die Frage, die neue Menschen und Modelle gleichermaßen nicht beantworten können, und veraltet nicht, weil sie Vergangenheit festhält.
Bringen Sie einen Pull Request mit, der zu groß war.
30 Minuten, kein Vertrieb. Wir gehen ihn durch und sagen, was ein Modell daran geändert hätte.
AI Engineering Review ansehen →
