Field Note: Was ich dokumentiere, bevor ich ein System ändere

Erst verstehen, dann anfassen

Wenn ich ein System ändere, dokumentiere ich zuerst seinen Zustand – nicht, weil ich möglichst viele Notizen sammeln möchte, sondern weil ich wissen will, worauf sich die Änderung auswirkt.

Der erste Impuls ist oft naheliegend: etwas wirkt doppelt, umständlich oder nicht mehr gebraucht. Man möchte aufräumen, vereinfachen, modernisieren. Gerade in einem gewachsenen System sagt der sichtbare Zustand aber wenig darüber aus, welche Aufgaben ein Teil tatsächlich erfüllt. Ein Plugin kann an einer Stelle erscheinen und an mehreren anderen mitwirken. Ein Feld kann im Backend unscheinbar wirken und zugleich Grundlage für einen Export, eine Schnittstelle oder eine redaktionelle Entscheidung sein.

Deshalb versuche ich, nicht mit der vermuteten Lösung zu beginnen. Ich will zunächst verstehen, welche Teile vorhanden sind, wie sie zusammenhängen und was als verlässlicher Ausgangszustand gelten kann. Das ist für mich der erste Schritt von Know → Change → Prove: Know.

Was ich heute anders mache: Früher hätte ich direkt bereinigt. Heute dokumentiere ich zuerst, was da ist und welche Funktion die betroffenen Teile im System haben könnten.

Was zum Zustand gehört

Bei einer WordPress-Installation reicht es mir nicht, eine Liste der aktiven Plugins anzuschauen. Die ist ein Teil des Bildes, aber kein Systemmodell. Ich halte auch Versionen, Custom Post Types, Taxonomien und Felder fest. Dazu kommen Datenbanken, Schnittstellen, Cronjobs, Webhooks, Rollen und externe Dienste, soweit sie zum betrachteten System gehören.

Die Frage ist dabei nicht, ob jede Einzelheit in ein langes Dokument muss. Entscheidend ist, dass die relevanten Abhängigkeiten sichtbar werden. Welche Inhalte werden wo gespeichert? Wer darf sie bearbeiten oder sehen? Welche Prozesse lesen oder verändern diese Daten? Gibt es Daten, die das System nach außen gibt oder von außen übernimmt? Und welche Aufgaben laufen unabhängig davon, ob gerade jemand im Backend arbeitet?

Ich dokumentiere lieber in einer Form, die sich später prüfen und vergleichen lässt. Eine Momentaufnahme kann zum Beispiel festhalten, welche Komponenten vorhanden sind und wie bestimmte Strukturen aussehen. Wenn ich nach einer Änderung dieselben Punkte erneut erfasse, entsteht eine Vergleichsgrundlage. Das hilft, Veränderungen von Annahmen zu trennen: Was hat sich tatsächlich verändert, und was war schon vorher so?

Dabei gehört auch dazu, Grenzen der Kenntnis zu notieren. Wenn ich einen Zusammenhang noch nicht sicher verstanden habe, schreibe ich das nicht glatt. Eine offene Frage ist nützlicher als eine scheinbar eindeutige Beschreibung, die auf Vermutungen beruht. Dokumentation soll Orientierung geben, nicht Sicherheit vortäuschen.

Die Änderung selbst beschreiben

Wenn der Ausgangszustand klarer ist, formuliere ich die geplante Änderung. Möglichst konkret: Was soll sich verändern? Warum? Welche Wirkung erwarte ich? Und welche anderen Teile könnten davon berührt werden?

Das klingt selbstverständlich, wird aber leicht übersprungen. „Aufräumen“ ist noch keine ausreichende Beschreibung einer Änderung. „Dieses Feld entfernen“ sagt noch nicht, ob es auch in einer Schnittstelle, einem automatisierten Ablauf oder einer redaktionellen Ansicht verwendet wird. Je genauer ich die Änderung eingrenze, desto besser kann ich prüfen, ob sie tatsächlich die gewünschte Wirkung hat.

Zu dieser Beschreibung gehört auch, was ausdrücklich gleich bleiben soll. Bei einer Datenmodelländerung können das bestimmte Inhalte oder ihre Zuordnung sein. Bei einer Anpassung an Rollen kann es darum gehen, dass bestehende Berechtigungen nicht unbemerkt erweitert oder eingeschränkt werden. Bei einer Änderung an einem Ablauf ist wichtig, welche Eingaben und Ergebnisse weiterhin erwartet werden. Die konkrete Prüfung hängt vom System ab; der Grundgedanke bleibt derselbe: Nicht nur die gewünschte Veränderung benennen, sondern auch die Invarianten.

Ich versuche außerdem, mögliche Seiteneffekte nicht als nachträgliche Überraschung zu behandeln. Dazu muss ich nicht so tun, als könnte ich alles im Voraus wissen. Es reicht, die naheliegenden Verbindungen zu prüfen und festzuhalten, wo noch Unsicherheit besteht. Ein begrenzter, nachvollziehbarer Eingriff ist leichter zu beurteilen als eine große Sammeländerung, bei der hinterher nicht mehr klar ist, welcher Teil welche Wirkung hatte.

Prüfen ist Teil der Änderung

Der dritte Schritt ist Prove: Ich lege fest, woran ich nach der Änderung erkenne, dass sie funktioniert hat. Das bedeutet mehr als zu prüfen, ob eine Seite noch lädt oder ein Bildschirm auf den ersten Blick richtig aussieht.

Ich frage: Welche Funktion muss weiterhin verfügbar sein? Welche Daten müssen identisch bleiben? Welche Schnittstelle oder welcher Ablauf braucht eine gezielte Prüfung? Und woran würde ich eine Regression erkennen? Die Antworten sollten sich auf die Änderung beziehen. Eine allgemeine Aussage wie „alles testen“ ist nicht so hilfreich wie eine kleine, konkrete Prüfbeschreibung, die den betroffenen Bereich und das erwartete Ergebnis benennt.

Für mich gehören diese Prüfungen schon in die Planung. Wenn ich erst nach der Umsetzung überlege, wie sich Erfolg oder Regression erkennen lassen, fehlt möglicherweise der Vergleich zum vorherigen Zustand. Deshalb dokumentiere ich vorab, welche Merkmale ich später erneut anschaue. Das kann eine Struktur, ein Verhalten oder ein Datenbestand sein – je nachdem, was verändert wird.

So wird aus der Dokumentation kein Bericht, der im Nachhinein erklärt, was ich getan habe. Sie bildet die Verbindung zwischen Ausgangslage, Eingriff und überprüfbarer Wirkung. Das ist auch der Gedanke hinter dem Prinzip, das ich in der Engine Room verfolge: Zustand erfassen, eine Änderung nach Vorschau und Freigabe ausführen und ihre Wirkung belegen. Der Ablauf soll nicht nur festhalten, dass etwas geändert wurde, sondern nachvollziehbar machen, was sich geändert hat und ob das beabsichtigte Ergebnis eingetreten ist.

Dokumentation als Arbeitsmittel

Eine Sache hat sich bei mir verändert: Ich denke Dokumentation nicht mehr als Aufgabe, die nach dem Projekt noch erledigt werden muss. Sie gehört für mich zur Veränderung selbst. Sie beeinflusst, wie groß ich den Eingriff anlege, welche Fragen ich vorher stelle und ob ich die Wirkung anschließend überhaupt beurteilen kann.

Das heißt nicht, dass ich vor jeder kleinen Anpassung ein umfassendes Handbuch schreibe. Der Umfang sollte zum Eingriff passen. Manchmal genügt eine knappe Zustandsaufnahme mit den relevanten Komponenten, der geplanten Änderung und den Prüfungen danach. Bei einem System mit vielen Datenmodellen, Rollen oder Schnittstellen muss ich mehr Zusammenhänge sichtbar machen. Entscheidend ist nicht die Länge der Dokumentation, sondern ob sie für die nächste Entscheidung brauchbar ist.

Mit WP Scope beschäftige ich mich in diesem Zusammenhang mit dem Erfassen und Vergleichen von Zuständen. Für mich liegt der Wert solcher Aufnahmen nicht darin, möglichst viel Material zu erzeugen. Sie helfen dann, wenn ich damit Unterschiede erkennen und eine Änderung in ihrem Kontext beurteilen kann. Eine Aufzeichnung ohne Bezug zu einer konkreten Entscheidung bleibt schnell Ablage. Ein Vergleich kann dagegen zeigen, wo ich genauer hinschauen muss.

Inzwischen behandle ich die Dokumentation deshalb wie ein Werkzeug am Arbeitstisch. Ich greife darauf zurück, wenn ich den Zustand verstehen, einen Eingriff begrenzen oder später eine Wirkung belegen will. Sie ist nicht die ganze Arbeit und ersetzt keine fachliche Prüfung. Aber ohne sie wird es schwerer, sauber zu unterscheiden zwischen dem, was ich ändern wollte, dem, was ich tatsächlich geändert habe, und dem, was dabei sonst noch passiert ist.

Meine Faustregel: Bevor ich ändere, halte ich fest, was da ist, warum ich eingreife und woran ich danach erkenne, dass die Änderung funktioniert – einschließlich dessen, was gleich bleiben muss.

Weiterführend

• Know → Change → Prove: Wie WordPress-Änderungen sicher werden
• WordPress technisch dokumentieren: Was eine gute Systemdokumentation enthalten sollte
• Engine Room