Dokumentation für Legacy-Software: Wie man nachträglich Ordnung schafft

Irgendwo in Ihrem Unternehmen läuft ein System, das niemand mehr vollständig versteht. Vielleicht hat es der Entwickler gebaut, der vor drei Jahren gegangen ist. Vielleicht existiert eine Dokumentation, aber sie beschreibt die Software von 2015, nicht die von heute. Oder es gibt schlicht gar nichts.

Das ist kein Einzelfall. Legacy software dokumentation erstellen gehört zu den Aufgaben, die immer wieder aufgeschoben werden, weil andere Dinge dringlicher erscheinen. Bis ein Problem entsteht und plötzlich niemand mehr weiß, wie das System eigentlich funktioniert.

Dieser Artikel zeigt, wie man nachträglich brauchbare Dokumentation aufbaut. Pragmatisch, ohne monatelange Projekte.

Warum Legacy-Systeme keine Dokumentation haben

Das ist keine Frage der Sorglosigkeit. Es ist eine Frage der Umstände.

Software entsteht unter Zeitdruck. Die erste Version wird gebaut, damit sie läuft. Dokumentation ist für später geplant. Später kommt selten.

Dann wächst das System. Neue Funktionen kommen hinzu. Alte werden angepasst. Jeder Entwickler, der daran arbeitet, kennt "seinen" Teil. Niemand hat einen vollständigen Überblick. Und niemand dokumentiert rückwirkend, was bereits existiert.

Hinzu kommt: Viele ältere Projekte wurden von einer einzigen Person gebaut und betrieben. Das Wissen sitzt im Kopf dieser Person, nicht im System. Solange diese Person da ist, fällt das nicht auf.

Was fehlende Dokumentation in der Praxis bedeutet

Stellen Sie sich vor: Es ist 22 Uhr. Die Webanwendung reagiert nicht mehr. Ihr Entwickler öffnet den Code und sieht tausende Zeilen, die niemand in den letzten Jahren angefasst hat.

Wo fängt man an? Welche Konfigurationsdatei ist relevant? Warum gibt es drei verschiedene Datenbankverbindungen? Was macht diese Funktion mit dem Namen process_data_v2_final_FINAL.php?

Ohne Dokumentation kostet jede Fehlersuche das Dreifache. Jede Übergabe an einen neuen Entwickler startet bei null. Jede Änderung am System birgt das Risiko, unbekannte Abhängigkeiten zu treffen.

Technische Schulden entstehen nicht nur durch schlechten Code. Fehlende Dokumentation ist selbst eine technische Schuld, die sich mit der Zeit verzinst.

Wo man mit der Dokumentation anfängt

Der häufigste Fehler: Man will alles auf einmal dokumentieren. Das scheitert immer.

Stattdessen empfiehlt sich ein anderer Ansatz: Fangen Sie dort an, wo der Schmerz am größten ist.

Schritt 1: Das System in drei Sätzen beschreiben

Was macht diese Software? Für wen? Welche Daten verarbeitet sie?

Diese drei Sätze klingen trivial. Aber in vielen Projekten gibt es sie nicht schriftlich. Als erstes Dokument sind sie unschätzbar wertvoll. Jeder neue Entwickler, jeder neue Dienstleister, jeder Nachfolger braucht genau das als Einstieg.

Schritt 2: Den Betrieb dokumentieren

Nicht den Code. Den Betrieb.

Wo läuft das System? Welcher Server, welcher Hoster, welche Zugangsdaten (sicher verwahrt)? Was passiert wenn der Server neu gestartet werden muss? Gibt es einen automatischen Start, oder muss jemand manuell eingreifen?

Diese Informationen fehlen am häufigsten. Und sie werden am dringendsten gebraucht, wenn etwas schiefläuft.

Schritt 3: Kritische Abläufe beschreiben

Was sind die drei bis fünf wichtigsten Funktionen des Systems? Der Bestellprozess. Die Nutzerverwaltung. Der nächtliche Datenimport.

Für jeden dieser Abläufe: Eine kurze Beschreibung, was passiert, welche Dateien oder Komponenten beteiligt sind, und was zu tun ist, wenn dieser Ablauf nicht funktioniert.

Das ist kein vollständiges technisches Handbuch. Es ist ein Erste-Hilfe-Kasten.

Schritt 4: Bekannte Probleme und Workarounds festhalten

Fast jede Legacy-Software hat sie: Dinge, die nicht richtig funktionieren, aber mit einem bekannten Workaround beherrschbar sind. Ein Feld, das nie geleert werden darf. Ein Prozess, der jeden Montag manuell angestoßen werden muss. Ein Fehler, der sich mit einem Neustart beheben lässt.

Dieses Wissen lebt im Kopf von Personen, nicht im System. Es gehört aufgeschrieben, bevor diese Personen das Unternehmen verlassen.

Was gute Dokumentation nicht ist

Dokumentation muss nicht perfekt sein, um nützlich zu sein.

Eine Textdatei im Projektverzeichnis ist besser als nichts. Ein kommentierter Ablaufplan im Stil von "Wenn X passiert, prüfe Y" ist besser als eine elegante, aber unvollständige Wiki-Seite.

Es gibt keine Pflicht, ein professionelles Dokumentationssystem einzuführen. Confluence, Notion, ein einfaches Markdown-Dokument: Das Format ist zweitrangig. Der Inhalt zählt.

Wichtig ist nur: Die Dokumentation muss auffindbar sein. Nicht in der persönlichen Dropbox des letzten Entwicklers. Nicht in einem E-Mail-Verlauf von 2018.

Wann man externe Hilfe braucht

Manchmal ist der Code so undurchsichtig, dass selbst erfahrene Entwickler länger brauchen, um ihn zu verstehen, als neu zu schreiben.

In diesen Fällen lohnt es sich, jemanden hinzuzuziehen, der Legacy Software kennt und weiß, wie man sich durch gewachsenen Code arbeitet. Nicht um alles zu dokumentieren, sondern um die wichtigsten Teile zu verstehen und verständlich zu machen.

Das Ergebnis ist keine vollständige Dokumentation. Aber es ist genug, um den Betrieb zu sichern und Wartungsarbeiten realistisch zu machen.

Dokumentation als laufende Aufgabe

Nachträgliche Dokumentation ist ein Anfang. Kein dauerhafter Zustand.

Wer die Software-Wartung professionell betreibt, hält Dokumentation aktuell. Jede Änderung am System wird kurz festgehalten. Nicht als Roman. Als Notiz: Was wurde geändert, warum, und was ist dabei zu beachten.

Das kostet pro Änderung fünf Minuten. Es spart beim nächsten Eingriff Stunden.

Fazit: Brauchbar schlägt vollständig

Viele Unternehmen warten mit der Dokumentation, weil sie das Thema für alles-oder-nichts halten. Entweder eine vollständige, professionelle Dokumentation, oder gar nichts.

Das ist der falsche Ansatz. Brauchbar schlägt vollständig jedes Mal.

Fangen Sie mit dem Betrieb an. Beschreiben Sie, was das System tut. Halten Sie bekannte Probleme fest. Das dauert keinen Monat. Das dauert einen Nachmittag.

Sprechen Sie uns an, wenn Sie nicht wissen, wo anfangen. Wir schauen uns Ihr System an und helfen dabei, die wichtigsten Lücken zu schließen. Das Erstgespräch ist kostenlos.