Fehlende Dokumentation bei gewachsenen Strukturen — und wie wir das lösen

Gewachsene IT-Strukturen sind wie alte Gebäude. Sie haben Charakter, einen nachvollziehbaren Ursprung und oft erstaunlich robuste Fundamente. Aber sie haben auch Wände, die sich niemand mehr anzurühren traut, Kabelschächte, die nicht beschriftet sind, und Schlüssel, von denen niemand weiß, welche Tür sie öffnen. Wenn wir mit neuen Kunden in ein Erstgespräch gehen, ist dies in neun von zehn Fällen der zentrale Schmerzpunkt: Es fehlt Dokumentation zu zentralen Bestandteilen.

Wir wollen diesen Beitrag nutzen, um unsere Sicht auf Dokumentation zu schildern und zu zeigen, wie wir in Bestands­projekten methodisch Ordnung schaffen — ohne dass Sie dafür ein halbjähriges Dokumentations­projekt aufsetzen müssen.

Warum Dokumentation fehlt — und das kein Vorwurf ist

Fehlende Dokumentation ist selten das Ergebnis von Nachlässigkeit. Sie ist das Ergebnis von Druck. Unter Zeitdruck entstehen Lösungen. Unter Kostendruck wird eingespart, was nicht unmittelbar sichtbar ist. Unter Personaldruck wird priorisiert, was sofort brennt. Dokumentation ist in all diesen Fällen die Aufgabe, die morgen gemacht werden soll. Und manchmal kommt dieses Morgen sieben Jahre später.

Das Problem zeigt sich erst, wenn der Kollege kündigt, das System upgraded werden muss oder ein externer Dienstleister Zugriff braucht. Plötzlich stellt sich heraus, dass niemand die Architektur vollständig erklären kann, dass mündliche Absprachen die einzige Wahrheitsquelle waren und dass der Grund für eine bestimmte Konfiguration längst vergessen ist.

Unser Grundsatz: Dokumentation entsteht im Tun

Wir glauben nicht an große Dokumentations­projekte, die nach einem halben Jahr ein Wiki hinterlassen, das niemand liest. Wir glauben an Dokumentation, die im laufenden Betrieb entsteht, nah am Code, nah an den Entscheidungen, nah an den Betriebsabläufen. Drei Werkzeuge sind dafür zentral.

1. Automatisierte Doku aus der Quelle

Viele Inhalte, die in klassischen Wikis mühsam gepflegt werden, sind in den Systemen selbst schon vorhanden. Infrastruktur-Beschreibungen stecken im Terraform-Code. Datenbank-Strukturen stecken im Migrationshistorie. CMS-Konfigurationen stecken in Composer-Dateien und YAML-Setups. Wir setzen Werkzeuge ein, die aus diesen Quellen automatisch lesbare Dokumentation erzeugen — und zwar bei jedem Build neu.

Der Vorteil: Diese Dokumentation ist immer aktuell. Sie ist nicht der letzte Stand vor drei Jahren, sondern der Stand von heute Vormittag. Für uns und für Sie heißt das, dass niemand mehr vor einer Frage wie „Welche Version läuft gerade wirklich?“ steht. Die Antwort ist dokumentiert, weil sie Teil des Systems ist.

2. Architecture Decision Records (ADRs)

Automatisch erzeugte Doku kann sagen, was ist. Sie kann nicht sagen, warum es so ist. Genau dafür nutzen wir Architecture Decision Records. Ein ADR ist ein kurzes, standardisiertes Dokument, das eine konkrete Architektur­entscheidung beschreibt: den Kontext, die betrachteten Alternativen, die getroffene Entscheidung und die bewussten Konsequenzen.

Wir legen ADRs direkt im Projekt-Repository ab, nummeriert, mit Datum und Verantwortlichen. Wenn in drei Jahren jemand fragt, warum ein bestimmter Dienst nicht in Kubernetes läuft oder warum wir eine bestimmte Extension vermieden haben, ist die Antwort nachvollziehbar. Das spart nicht Zeit beim Schreiben — es spart Zeit bei der Rechtfertigung, Diskussion und bei dem Versuch, alte Fehler zu wiederholen.

3. Runbooks für den Betrieb

Die dritte Säule unserer Dokumentation sind Runbooks. Ein Runbook beschreibt schrittweise, wie eine wiederkehrende operative Aufgabe ausgeführt wird: ein TYPO3-Major-Upgrade, ein Datenbank-Failover, ein Restore aus einem Backup, das Onboarding eines neuen Redakteurs. Runbooks werden nicht von theoretisierenden Menschen geschrieben, sondern von denen, die den Schritt tatsächlich ausgeführt haben.

Für Sie heißt das: Aufgaben sind nicht an Personen gekoppelt. Wenn jemand ausfällt, kann ein anderer ordentlich übernehmen. Wenn wir in einem Projekt mit Ihren internen Teams arbeiten, werden Runbooks zum gemeinsamen Ort für operatives Wissen.

Wie wir in bestehenden Systemen vorgehen

Wenn wir ein Bestandssystem übernehmen, starten wir nicht mit dem Anspruch, die vollständige Geschichte zu rekonstruieren. Wir starten mit einer Bestandsaufnahme: Was ist kritisch, was läuft, was ist ein Risiko? Auf dieser Basis priorisieren wir Dokumentations­arbeit so, dass wir zuerst dort Licht machen, wo das Risiko am größten ist — meistens an Schnittstellen, Konfigurationen mit Security-Bezug und Prozessen, die nur eine Person versteht.

Parallel dazu führen wir unsere drei Werkzeuge ein: automatisierte Doku, ADRs für neue Entscheidungen, Runbooks für die wichtigsten Betriebsabläufe. Ältere Entscheidungen, deren Kontext verloren ist, dokumentieren wir pragmatisch mit dem Vermerk, dass der ursprüngliche Grund nicht mehr ermittelbar ist. Das klingt banal, ist aber wichtig: Ehrlichkeit über Nicht­wissen ist Teil seriöser Dokumentation.

Was Sie davon haben

Planungssicherheit. Upgrades, Migrationen und Personalwechsel werden berechenbar, weil Wissen nicht mehr nur in Köpfen sitzt.

Schnelleres Onboarding. Neue Kolleginnen und Kollegen — intern und bei uns — finden sich in dokumentierten Systemen in Wochen zurecht, nicht in Monaten.

Bessere Sicherheit. Dokumentation ist die Voraussetzung für saubere Audits und für schnelle Reaktionen auf CVEs.

Weniger Abhängigkeit. Sie sind nicht mehr von einer einzelnen Person oder einem einzelnen Dienstleister abhängig, nur weil nur dort das Wissen liegt.