Dokumentation für Systeme, die niemand mehr versteht

Der Entwickler, der das System gebaut hat, ist seit drei Jahren weg. Die Dokumentation besteht aus einem veralteten Wiki mit Bildern, die nicht mehr laden, und Kommentaren im Code wie // TODO: fix later. Das System läuft. Irgendwie. Aber niemand traut sich, es anzufassen. Willkommen in der Realität von Legacy-Dokumentation.

Dokumentation nachträglich zu erstellen ist möglich. Es erfordert Archäologie, nicht Kreativität.

Warum überhaupt dokumentieren?

„Der Code ist die Dokumentation" – das sagen Leute, die nie um 3 Uhr nachts einen Bug in fremdem Code fixen mussten.

Dokumentation für Legacy-Systeme hat konkrete Ziele:

• Onboarding: Neue Teammitglieder produktiv machen, ohne dass jemand 6 Wochen erklärt
• Incident Response: Im Notfall wissen, wo man suchen muss
• Änderungen: Verstehen, was kaputt gehen könnte, bevor man etwas anfasst
• Compliance: Audits, Due Diligence, Zertifizierungen
• Exit-Strategie: Basis für Migration, Ablösung oder Verkauf

Was dokumentieren? Die Prioritäten

Nicht alles ist gleich wichtig. Hier ist die Reihenfolge, die sich in der Praxis bewährt hat:

Priorität 1: Das Überlebenswissen

Was jeder wissen muss, der das System betreiben oder im Notfall anfassen muss:

• System-Kontext: Was macht das System? Für wen? Warum existiert es?
• Kritische Pfade: Welche Funktionen dürfen nie ausfallen?
• Deployment: Wie kommt Code in Produktion? Rollback?
• Betrieb: Wo laufen die Prozesse? Logs? Monitoring?
• Kontakte: Wer weiß was? Wer ist verantwortlich?

Priorität 2: Die Architektur

Wie hängt alles zusammen? Keine UML-Diagramme, die niemand versteht – einfache Boxen und Pfeile.

• Komponenten-Diagramm: Was sind die Hauptteile?
• Datenfluss: Woher kommen Daten, wohin gehen sie?
• Integrationen: Welche externen Systeme sind angebunden?
• Datenbank-Schema: Die wichtigsten Tabellen und Beziehungen

Priorität 3: Die Entscheidungen

Warum ist etwas so, wie es ist? Das ist das Wissen, das am schnellsten verloren geht.

• Architecture Decision Records (ADRs): Dokumentierte Entscheidungen
• Bekannte Limitierungen: Was geht nicht, und warum?
• Workarounds: Hacks, die aus gutem Grund existieren
• „Das ist Absicht": Verhalten, das wie ein Bug aussieht, aber keiner ist

Priorität 4: Die Fallstricke

Wissen, das nur durch Schmerz erworben wurde:

• Bekannte Bugs: Die, die man nicht fixen kann oder will
• Performance-Fallen: „Diese Query nicht in der Hauptlast ausführen"
• Konfiguration: Einstellungen, die das System zum Absturz bringen
• Zeitbomben: Dinge, die irgendwann zum Problem werden

Reverse Documentation: Vom Code zur Dokumentation

Wenn keine Dokumentation existiert, müssen Sie sie aus dem System extrahieren. Das ist Archäologie, keine Kreativität.

Schritt 1: Code lesen lassen

Nutzen Sie Tools, die Code analysieren:

# Abhängigkeiten visualisieren (PHP)
dephpend metrics src/ --format=html > dependencies.html

# Klassen-Diagramm generieren (Java)
java -jar plantuml.jar -tpng src/**/*.java

# Call-Graph erstellen (Python)
pycallgraph graphviz -- ./main.py

# Datenbank-Schema dokumentieren (je nach DB: mysqldump / pg_dump)
mysqldump --no-data mydb | grep -E "^(CREATE|PRIMARY|KEY|CONSTRAINT)" > schema.sql
# Oder mit SchemaSpy für visuelle Darstellung
java -jar schemaspy.jar -t mysql -db mydb -host localhost -u user -p -o docs/

Schritt 2: Git-Archäologie

Die Git-Historie erzählt Geschichten:

# Wer hat am meisten an welchen Dateien gearbeitet?
git shortlog -sn --all -- src/

# Welche Dateien ändern sich am häufigsten?
git log --pretty=format: --name-only | sort | uniq -c | sort -rn | head -20

# Wann wurde eine Datei zuletzt geändert?
git log -1 --format="%ai %an" -- src/CriticalModule.php

# Commit-Messages für eine Datei (die Geschichte)
git log --oneline -- src/BillingService.php

# Wer weiß noch etwas über diesen Code?
git log --format="%an <%ae>" -- src/LegacyAuth/ | sort | uniq

Schritt 3: Laufzeit-Analyse

Beobachten Sie das System bei der Arbeit:

# Welche Queries laufen? (MySQL)
SET GLOBAL slow_query_log = 'ON';
SET GLOBAL long_query_time = 0.1;
# Später: mysqldumpslow /var/log/mysql-slow.log

# Welche Endpoints werden genutzt? (aus Access Logs)
awk '{print $7}' access.log | sort | uniq -c | sort -rn | head -30

# Welche Jobs laufen? (Crontab dokumentieren)
crontab -l > docs/crontab.txt
for user in $(cut -f1 -d: /etc/passwd); do
    crontab -u $user -l 2>/dev/null
done > docs/all-crontabs.txt

# Netzwerk-Verbindungen (welche Services reden miteinander?)
netstat -tuln
ss -tuln

Schritt 4: Interviews

Menschen wissen Dinge, die nirgendwo stehen:

• Älteste Teammitglieder: „Warum ist das so?"
• Support-Team: „Welche Probleme kommen immer wieder?"
• Ops/DevOps: „Was geht nachts kaputt?"
• Business/Product: „Was ist kritisch? Was darf nie ausfallen?"

Formate, die funktionieren

Das README, das niemand liest

Ein README wird gelesen, wenn es kurz ist und die richtigen Fragen beantwortet:

# System-Name

## Was ist das?
[Ein Satz]

## Quickstart
```bash
docker-compose up
# App läuft auf http://localhost:8080
```

## Architektur
[Ein Diagramm oder Link zu Diagramm]

## Deployment
[Wie kommt das in Produktion?]

## Troubleshooting
- Problem X: Lösung Y
- Problem A: Lösung B

## Wer weiß mehr?
- Team Billing: #billing-dev (Slack)
- Auth/Security: @security-oncall
- Infrastruktur: ops@example.com

Runbooks für Operations

Schritt-für-Schritt-Anleitungen für wiederkehrende Aufgaben:

Architecture Decision Records (ADRs)

ADRs dokumentieren das „Warum" – das Wissen, das am schnellsten verloren geht.

# Verzeichnisstruktur
docs/
  adr/
    0001-use-mysql-instead-of-postgres.md
    0002-caching-strategy-redis.md
    0003-authentication-via-oauth.md
    template.md

ADRs sind besonders wertvoll, weil sie Kontext liefern. „Warum nutzen wir MySQL statt Postgres?" – Wenn Sie das nicht dokumentieren, wird jemand in 2 Jahren die gleiche Diskussion führen.

Inline-Dokumentation, die hilft

Kommentare im Code, die tatsächlich nützlich sind:

// SCHLECHT: Was der Code tut (sieht man)
// Erhöht den Counter um 1
counter++;

// GUT: Warum der Code das tut
// Counter muss vor dem API-Call erhöht werden,
// weil die externe API idempotent ist und
// duplicate Requests anhand des Counters erkennt
counter++;

// NOCH BESSER: Warnung vor Fallstrick
// ACHTUNG: Diese Funktion ist nicht thread-safe!
// Bei parallelen Aufrufen kann es zu Race Conditions kommen.
// Siehe Incident INC-2023-047 für Details.
function processPayment() { ... }

// GOLD: Link zu mehr Kontext
// Implementiert Algorithmus aus RFC 7519 (JWT)
// Abweichung von Standard: Wir nutzen RS256 statt HS256
// Grund: siehe ADR-0012
function validateToken() { ... }

Tribal Knowledge extrahieren

Das gefährlichste Wissen ist das, das nur in Köpfen existiert. Hier ist, wie Sie es extrahieren:

Die „Bus Factor"-Analyse

Bus Factor: Wie viele Personen dürfen ausfallen, bevor kritisches Wissen verloren geht?

# Git-Analyse: Wer kennt welchen Code?
git log --format='%an' --since="2 years ago" -- src/billing/ | sort | uniq -c | sort -rn

# Ergebnis:
#    847 Maria Schmidt      ← Maria kennt Billing
#    123 Thomas Müller
#     45 Extern Consultant
#      3 CI Bot

# Wenn Maria geht, geht 87% des Billing-Wissens mit.

Identifizieren Sie Wissenszentren und planen Sie Knowledge Transfer.

Die „Letzte Person"-Interviews

Bevor jemand das Team verlässt:

• Welche Systeme verstehst nur du?
• Was würdest du deinem Nachfolger sagen?
• Welche Dokumentation fehlt?
• Welche Entscheidungen hast du getroffen, die nirgendwo stehen?
• Was geht regelmäßig kaputt, und wie fixt man es?

Pair Programming zur Wissensweitergabe

Die effektivste Methode, Wissen zu transferieren:

• Experte erklärt, während er arbeitet
• Lernender stellt Fragen und dokumentiert
• Aufzeichnung (mit Erlaubnis) für spätere Referenz

Eine Stunde Pair Programming produziert mehr nutzbares Wissen als ein Tag Dokumentation schreiben.

Dokumentation aktuell halten

Die größte Herausforderung: Dokumentation veraltet. Immer. Verifizieren Sie jede Aussage gegen Code oder Laufzeitverhalten. Hier sind Strategien, die helfen:

Dokumentation im Code-Repository

Wenn Dokumentation neben dem Code liegt, wird sie eher aktualisiert:

project/
├── src/
├── tests/
├── docs/
│   ├── architecture/
│   │   ├── overview.md
│   │   └── diagrams/
│   ├── adr/
│   ├── runbooks/
│   └── onboarding.md
└── README.md

Pull Requests können dann Dokumentations-Updates enthalten. Review-Prozess erfasst auch Docs.

Automatisch generierte Dokumentation

Was automatisch generiert wird, ist immer aktuell:

• API-Dokumentation: OpenAPI/Swagger aus Code generieren
• Datenbank-Schema: Automatische Schema-Extraktion
• Dependency-Graphen: Tools wie dephpend, madge
• Metriken: SonarQube, CodeClimate Reports

# OpenAPI aus Code generieren (PHP/Laravel)
php artisan l5-swagger:generate

# TypeScript/Node
npx @hey-api/openapi-ts -i ./openapi.yaml -o ./src/client

# Schema-Dokumentation (PostgreSQL)
pg_dump --schema-only mydb > schema.sql
# Oder mit dbdocs.io für visuelle Darstellung

Regelmäßige Reviews

Dokumentation braucht Pflege wie Code:

• Quartalsweise: Architektur-Diagramme noch korrekt?
• Bei jedem Incident: Runbooks aktualisieren
• Beim Onboarding: Neue Mitarbeiter dokumentieren, was fehlt
• Beim Offboarding: Wissenstransfer dokumentieren

Anti-Patterns: Was nicht funktioniert

1. Das 200-Seiten-Dokument

Niemand liest es. Niemand aktualisiert es. Es wird zur historischen Fiktion.

2. Das Wiki ohne Struktur

Hunderte Seiten, keine Navigation, Suchfunktion liefert 47 Treffer für „deployment". Information existiert, ist aber nicht findbar.

3. Dokumentation als Projekt

„Wir dokumentieren jetzt 3 Monate, dann sind wir fertig." Falsch. Dokumentation ist ein Prozess, kein Projekt. Es ist nie fertig.

4. Nur Architekten dokumentieren

Die Leute, die täglich im Code arbeiten, wissen am meisten. Wenn nur Architekten dokumentieren, fehlt das Praxiswissen.

5. Dokumentation ohne Zielgruppe

„Dokumentation" ist kein Selbstzweck. Wer soll das lesen? Was sollen sie danach können? Ohne Antwort auf diese Fragen ist jede Dokumentation Zeitverschwendung.

Quick Wins: Sofort umsetzbar

Sie haben wenig Zeit? Hier sind die Maßnahmen mit dem besten ROI:

Maßnahme	Aufwand	Wert
1-Seite-System-Überblick	2 Stunden	Hoch
Deployment-Runbook	1 Stunde	Sehr hoch
Kontaktliste „Wer weiß was"	30 Minuten	Hoch
Architektur-Skizze (Whiteboard-Foto)	30 Minuten	Mittel
Git-Analyse: Wer kennt was	15 Minuten	Mittel
Top-10-Fallstricke-Liste	1 Stunde	Sehr hoch

Fazit

Legacy-Dokumentation ist keine Frage von „ob", sondern „wann". Entweder Sie dokumentieren proaktiv, oder Sie dokumentieren in der Krise – nachts, unter Druck, wenn das System brennt.

Die wichtigsten Punkte:

• Priorisieren: Überlebenswissen zuerst, Details später
• Extrahieren: Code, Git, Logs, Menschen – alles sind Quellen
• Pragmatisch: Ein Whiteboard-Foto ist besser als nichts
• Nah am Code: Dokumentation im Repository, nicht im vergessenen Wiki
• Lebendig: Neue Mitarbeiter dokumentieren, was fehlt

Das beste Dokument ist das, das jemand liest, wenn er es braucht. Alles andere ist Papier.

---