PHP-Anwendung ohne Dokumentation übernehmen: So gehst du vor

«Es gibt keine Dokumentation» ist der häufigste Satz zu Beginn einer Übernahme. Er stimmt selten ganz. Eine laufende Anwendung dokumentiert sich in gewisser Weise selbst: im Code, in der Versionshistorie, im Datenbankschema, in der Serverkonfiguration und in den Köpfen der Leute, die sie täglich nutzen. 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 den Nutzern: Wer täglich mit der Anwendung arbeitet, kennt die Abläufe, Sonderfälle und bekannten Macken.

In fünf Schritten zur beherrschbaren Anwendung

1. Inventar erstellen. PHP-Version, Framework und Version, Abhängigkeiten laut composer.json und composer.lock, Datenbank, Server, externe Dienste. Das Ergebnis ist eine Liste, die zeigt, womit man es zu tun hat.
2. Lauffähige Kopie aufsetzen. Die Anwendung läuft in einer Testumgebung mit derselben PHP-Version wie produktiv. Personendaten werden dafür anonymisiert, damit die Testumgebung auch im Sinne des Datenschutzgesetzes unkritisch bleibt.
3. Einstiegspunkte und Datenflüsse erfassen. Welche Seiten und Schnittstellen gibt es, welche Cronjobs und Queues laufen, welche Daten fliessen woher und wohin?
4. 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.
5. Dokumentation mitwachsen lassen. Alles, was in den ersten vier Schritten herausgefunden wird, 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 verhindert man, 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 bei meinen Übernahmen Code und Dokumentation in einem Repository, auf das der Kunde jederzeit Zugriff hat, und alle Zugangsdaten in einem gemeinsamen Passwort-Tresor. So kann jederzeit auch jemand anderes übernehmen. Wie der Einstieg aussieht, zeigt die Seite Webapplikation übernehmen.