Eine laufende Anwendung dokumentiert sich in gewisser Weise selbst. Die Aufgabe ist, dieses verstreute Wissen einzusammeln und aufzuschreiben.
Wo steckt das Wissen, wenn es keine Doku gibt?
- Im Code: Routen, Controller, Modelle und Konfiguration zeigen, was die Anwendung tut.
- In der Versionshistorie: Commit-Nachrichten und Änderungen erklären, warum etwas so gebaut wurde.
- In der Datenbank: Tabellen, Beziehungen und Datenmengen zeigen, was wirklich genutzt wird.
- Auf dem Server: Cronjobs, Webserver-Konfiguration, Umgebungsvariablen und Logs zeigen, was im Hintergrund läuft.
- Bei deinen Leuten: Wer täglich mit der Anwendung arbeitet, kennt die Abläufe, Sonderfälle und bekannten Macken.
Wie viel sich aus einem laufenden System zurückholen lässt, zeigt ein Projekt, bei dem das alte CMS weder eine API noch direkten Datenbankzugriff bot. Ein eigens entwickelter Scraper hat die ganze Website mit Tausenden Seiten erfasst, samt Hierarchie, Medien und Übersetzungen, und sie vollautomatisch nach TYPO3 übertragen: automatisierte CMS-Migration zu TYPO3.
In fünf Schritten zur beherrschbaren Anwendung
- Inventar erstellen. PHP-Version, Framework und Version, Abhängigkeiten laut
composer.jsonundcomposer.lock, Datenbank, Server, externe Dienste. Das Ergebnis ist eine Liste, die dir zeigt, womit du es zu tun hast. - Lauffähige Kopie aufsetzen. Die Anwendung läuft in einer Testumgebung mit derselben PHP-Version wie produktiv. Personendaten sind dort anonymisiert, damit die Testumgebung auch im Sinne des Datenschutzgesetzes unkritisch bleibt.
- Einstiegspunkte und Datenflüsse erfassen. Welche Seiten und Schnittstellen gibt es, welche Cronjobs und Queues laufen, welche Daten fliessen woher und wohin?
- Kritische Abläufe mit Tests absichern. Charakterisierungstests halten fest, wie sich Bestellung, Login oder Datenimport heute verhalten. Ab dann fällt jede ungewollte Änderung sofort auf.
- Dokumentation mitwachsen lassen. Alles, was die ersten vier Schritte zutage fördern, landet im Repository. So entsteht die Dokumentation nicht als Extraprojekt, sondern als Nebenprodukt der Arbeit.
Welche Dokumentation braucht eine übernommene Anwendung?
| Dokument | Inhalt | Für wen |
|---|---|---|
| README | Aufsetzen, lokal starten, wichtigste Befehle | Jede Person, die am Code arbeitet |
| Betriebshandbuch | Deployment, Backups, Cronjobs, Monitoring, Notfallablauf | Betrieb und Support |
| Schnittstellenübersicht | Externe Dienste, Datenflüsse, Zugänge (ohne Passwörter) | Entwicklung und Fachabteilung |
| Architekturübersicht | Aufbau, wichtigste Komponenten, bekannte Schwachstellen | Entwicklung und Entscheider |
| Entscheidungsprotokoll | Warum etwas so gebaut oder geändert wurde | Alle, die später Entscheidungen treffen |
Das Entscheidungsprotokoll folgt der Idee der Architecture Decision Records von Michael Nygard: kurze, datierte Einträge, die festhalten, welche Entscheidung warum getroffen wurde.
Wie verhinderst du, dass es wieder so weit kommt?
Das eigentliche Problem einer undokumentierten Anwendung ist nicht die fehlende Doku, sondern die Abhängigkeit von einer einzigen Person. Deshalb liegen Code und Dokumentation nach der Übernahme in einem Repository, auf das du jederzeit Zugriff hast, und alle Zugangsdaten in einem gemeinsamen Passwort-Tresor. So kann jederzeit auch jemand anderes übernehmen, auch ohne mich. Mit der laufenden Wartung wächst die Dokumentation bei jeder Änderung mit, statt wieder zu veralten. Wie der Einstieg aussieht, zeigt die Seite Webapplikation übernehmen. Worauf es bei einem halbfertigen Projekt oder KI-generiertem Code zusätzlich ankommt, steht im Artikel halbfertiges Projekt übernehmen.
Quellen
- [1]Characterization test · Wikipedia
- [2]Documenting Architecture Decisions · Michael Nygard, Cognitect, 2011
- [3]Bus-Faktor · Wikipedia
- [4]Bundesgesetz über den Datenschutz (DSG) · Fedlex, Schweizerische Eidgenossenschaft