Technische Dokumentation für Legacy-Software erstellen: Der pragmatische Ansatz

Sie wollen technische Dokumentation für Legacy-Software erstellen. Und Sie ahnen schon, was passiert. Jemand schätzt drei Monate. Das Projekt wird auf nach dem Quartalsabschluss verschoben. Dort bleibt es liegen.

Das kennt fast jedes Unternehmen mit älterer Software. Die Dokumentation fehlt, ist veraltet oder besteht aus einem Word-Dokument von 2014. Niemand traut sich, es zu öffnen.

Dabei geht es auch anders. Dokumentation muss nicht vollständig sein, um zu helfen. Sie muss nur die richtigen Fragen beantworten. Dieser Artikel zeigt, welche das sind.

Warum fehlt bei Legacy-Software fast immer die Dokumentation?

Das hat selten mit Schlamperei zu tun. Es hat mit Reihenfolge zu tun.

Software entsteht unter Zeitdruck. Features gehen live, Kunden warten, der nächste Termin steht. Dokumentation ist die Aufgabe, die man morgen macht. Und morgen ist wieder etwas anderes dringend.

Dann kommt der zweite Effekt. Wer ein System täglich betreut, braucht keine Dokumentation. Das Wissen sitzt im Kopf. Es fühlt sich nicht wie eine Lücke an, solange die Person da ist.

Genau das ist der Punkt. Dokumentation schützt nicht die Person, die das System kennt. Sie schützt alle anderen. Und das Unternehmen an dem Tag, an dem der letzte Entwickler geht.

Fehlende Dokumentation ist eine Form von technischen Schulden. Sie ist unsichtbar, kostet aber jeden Monat Zinsen. In Form von längeren Einarbeitungszeiten, teureren Angeboten und langsamerer Fehlersuche.

Was passiert, wenn Sie nichts tun?

Die Kosten fallen nicht auf einen Schlag an. Sie verteilen sich, und deshalb fallen sie kaum auf.

Jede Änderung wird teurer

Ein externer Entwickler, der ein undokumentiertes System übernimmt, kalkuliert einen Risikoaufschlag. Das ist keine Willkür. Er weiß nicht, was er findet.

In der Praxis sehen wir Aufschläge von 30 bis 50 Prozent auf Wartungsangebote, wenn keinerlei Unterlagen vorliegen. Bei kleinen Änderungen ist der Effekt noch größer. Zwei Stunden Arbeit werden zu acht, weil sechs davon Suchen sind.

Fehlersuche wird zum Ratespiel

Wenn nachts ein Prozess ausfällt, entscheidet die Dokumentation über die Ausfalldauer. Wer weiß, welcher automatische Job was tut und wohin er schreibt, ist in 20 Minuten fertig. Wer es nicht weiß, sucht bis zum Morgen.

Übergaben scheitern

Anbieterwechsel, Unternehmensnachfolge, interne Umstrukturierung. In all diesen Fällen wird geprüft, was man da eigentlich übernimmt. Fehlt die Dokumentation, sinkt der Wert des Systems in dieser Prüfung sofort. Wir haben das mehrfach bei einem Software-Audit vor der Übernahme erlebt.

Der pragmatische Ansatz: klein anfangen, richtig priorisieren

Der Fehler bei den meisten Dokumentationsprojekten liegt am Anfang. Man versucht, alles zu beschreiben. Das dauert Monate und wird nie fertig.

Drehen Sie die Frage um. Nicht: "Was gibt es alles?" Sondern: "Was braucht jemand, der morgen früh um 3 Uhr allein vor diesem System steht?"

Diese Frage lässt sich in wenigen Tagen beantworten.

Stufe 1: Das Notfallwissen (ein Tag)

Das ist die wichtigste Stufe. Ohne sie ist alles andere Luxus. Halten Sie fest:

• Wo läuft was? Server, Hostnamen, Zugänge, wer der Hoster ist und wie man ihn erreicht.
• Wie startet und stoppt man das System? Die konkreten Befehle, nicht die Theorie.
• Wo liegen die Daten? Datenbank, Dateiablagen, externe Speicher.
• Wo liegen die Backups und wie spielt man sie zurück? Ein ungetestetes Backup ist kein Backup.
• Welche Verträge und Lizenzen hängen dran? Domain, Zertifikate, Dienste von Dritten mit Ablaufdatum.
• Wer ist im Notfall zu erreichen? Mit Telefonnummer, nicht nur mit E-Mail.

Diese Liste passt auf zwei Seiten. Sie ist mehr wert als 200 Seiten Architekturbeschreibung.

Stufe 2: Der Systemüberblick (zwei bis drei Tage)

Jetzt kommt das Bild vom Ganzen. Eine Skizze reicht, gern handgezeichnet und abfotografiert.

Welche Bestandteile gibt es? Welche Anwendung spricht mit welcher Datenbank? Welche Schnittstellen gehen nach außen, zu welchen Partnern? Welche automatischen Abläufe gibt es, wann laufen sie und was passiert, wenn sie ausfallen?

Ergänzen Sie eine Liste der eingesetzten Versionen. Programmiersprache, Datenbank, Betriebssystem, wichtigste Bibliotheken. Diese Liste ist gleichzeitig Ihre Risiko-Übersicht. Was hier End of Life ist, gehört auf die Agenda.

Stufe 3: Die fachlichen Besonderheiten (laufend)

Jedes gewachsene System hat Stellen, die auf den ersten Blick falsch aussehen und es nicht sind. Der Rabatt, der nur für Bestandskunden aus einem bestimmten Jahr gilt. Der Export, der um 4 Uhr laufen muss, weil ein Partnersystem sonst dicht ist.

Dieses Wissen ist am wertvollsten und geht am schnellsten verloren. Halten Sie es fest, sobald jemand darüber stolpert. Ein Satz genügt: Was ist merkwürdig, und warum ist es so.

Stufe 4: Der Rest (später, vielleicht nie)

Ausführliche Code-Dokumentation, Klassendiagramme, vollständige Datenmodelle. Das ist schön, aber selten entscheidend. Machen Sie es dann, wenn Sie den Bereich ohnehin anfassen.

Welcher Minimalstandard reicht wirklich?

Halten Sie die Hürde niedrig. Drei Regeln haben sich bewährt.

Die Dokumentation liegt beim Code. Am besten als einfache Textdateien im Repository, also dort, wo auch der Quellcode verwaltet wird. Dann wird sie mitversioniert und geht bei Rechnerwechseln nicht verloren. Falls Sie noch keine Versionsverwaltung nutzen, ist das der richtige Zeitpunkt. Wir haben beschrieben, warum Git bei Legacy-Projekten oft fehlt und wie man es nachrüstet.

Jede Datei hat ein Datum und einen Namen. Wer nicht weiß, ob eine Notiz von gestern oder von 2015 ist, traut ihr nicht.

Unvollständig ist besser als leer. Eine Seite, die ehrlich sagt "diese drei Punkte sind ungeklärt", ist nützlich. Sie zeigt der nächsten Person, wo sie graben muss.

Alles Weitere ist Kür. Kein Wiki-Projekt, kein monatelanger Tool-Auswahlprozess, keine Vorlagen-Diskussion. Diese Debatten haben schon mehr Dokumentationsvorhaben beendet als Zeitmangel.

Wie bringen Sie Entwickler dazu, mitzuziehen?

Entwickler dokumentieren ungern, weil Dokumentation meist Doppelarbeit ohne sichtbaren Nutzen ist. Das lässt sich ändern.

Machen Sie es zur Arbeitsaufgabe, nicht zur Zusatzaufgabe. Dokumentation nach Feierabend passiert nie. Zwei Stunden pro Woche im Plan dagegen schon.

Dokumentieren Sie im Anlassfall. Wer gerade einen Fehler behoben hat, weiß am meisten über die Stelle. Genau dann kostet die Notiz fünf Minuten. Drei Wochen später kostet sie eine Stunde.

Zeigen Sie, dass es gelesen wird. Wenn eine Notiz einen Ausfall verkürzt hat, sagen Sie es. Nichts motiviert mehr als der Beweis, dass es etwas gebracht hat.

Verlangen Sie keine Schönheit. Stichpunkte reichen. Rechtschreibfehler sind erlaubt. Der Inhalt zählt.

Wenn intern niemand Zeit hat, ist das ein guter Anlass für Hilfe von außen. Wir übernehmen genau das im Rahmen von Dokumentation und Übergabe: das System analysieren, das Notfallwissen festhalten, den Überblick zeichnen. Bei den meisten Systemen ist die Basis in ein bis zwei Wochen fertig.

Wie eine solche Bestandsaufnahme im Detail abläuft, zeigt unser Artikel zur Dokumentation von Legacy-Software.

Ein realistischer Fahrplan

So sieht ein Start aus, der wirklich funktioniert:

1. Woche 1: Notfallwissen zusammentragen. Eine Datei, zwei Seiten, fertig.
2. Woche 2: Backup einmal testweise zurückspielen und den Vorgang dabei aufschreiben.
3. Woche 3 und 4: Systemüberblick skizzieren, Versionsliste erstellen, Risiken markieren.
4. Ab dann: Bei jeder Änderung die betroffene Stelle kurz beschreiben.

Nach einem Monat haben Sie die Dokumentation, die im Ernstfall zählt. Nach einem Jahr haben Sie deutlich mehr, ohne dass es je ein Projekt war.

Fazit: Zwei Seiten schlagen null Seiten

Technische Dokumentation für Legacy-Software zu erstellen scheitert fast immer am Anspruch, nicht am Aufwand. Wer alles will, bekommt nichts.

Fangen Sie beim Notfallwissen an. Halten Sie es dort fest, wo der Code liegt. Schreiben Sie weiter, wenn Sie ohnehin am System arbeiten. Das ist unspektakulär, und es funktioniert.

Sie wissen nicht, wo Sie anfangen sollen, oder niemand im Team hat die Zeit dafür? Sprechen Sie uns an. Wir schauen uns Ihr System an und sagen Ihnen ehrlich, was fehlt und was es kostet. Das Erstgespräch ist kostenlos.