Selbst-dokumentierende Artefakte, oder: was in sechs Monaten niemand mehr weiß
Schnelle Lösungen ohne Spur werden zur Zeitbombe. Wie ich jede deployte Sache so baue, dass sie erklärt, was sie ist, ohne den ursprünglichen Chat.
Ich finde schnelle Lösungen. Das ist das Problem. Ein DNS-Trick hier, ein Webhook dort, eine Custom-Integration, die genau eine Sache tut und sie gut tut. Alles läuft. Und in drei bis zwölf Monaten weiß niemand mehr, was da eigentlich gebaut wurde, warum, und wie man es anfasst, ohne es zu zerstören. Der ursprüngliche Chat ist weg, die Notiz unauffindbar. Genau dann wird der Quick-Fix zur Zeitbombe.
Die Antwort ist nicht „mehr Doku“. Separate Doku verrottet, weil sie nicht mit dem Artefakt mitreist. Die Antwort ist: die Doku lebt am Artefakt selbst.
Die Regel
Jede nicht-triviale Sache, die irgendwo lebt, ein deploytes File, eine Cloud-Ressource, ein Cron, ein Webhook, bekommt eine Spur, die sie überlebt, unabhängig von Chat, Memory oder mir:
1. Selbst-Doku im Artefakt. Ein Kommentar-Header direkt im deployten File oder in der Ressourcen-Beschreibung, der beantwortet: Was ist das, wo gehostet, wie ändern, wie eingebunden, seit wann. Bei Cloud-Ressourcen zusätzlich das Beschreibungsfeld des Anbieters nutzen, damit schon das Dashboard die Antwort trägt.
2. Ein Eintrag in der Infra-Karte. Pro System eine Zeile: was, wo, Zugang, wie ändern, zuletzt angefasst, warum so.
3. Datiert, mit einem kurzen „warum“. Das „warum“ ist in sechs Monaten Gold. Es ist ein Mini-ADR.
Der teuerste Fehler ist nicht fehlende Doku
Fehlende Doku bremst nur. Der wirklich teure Fall ist eine alte Aussage, die selbstbewusst das Gegenteil der Wahrheit behauptet. Die schickt den Nächsten aktiv in die falsche Richtung, und er merkt es nicht.
Deshalb: Wer etwas widerlegt, korrigiert es an seiner Stelle, nicht nur woanders richtig. Die alte Behauptung wird dort markiert, wo sie steht. Alte Stände löschen ist in Ordnung, sie unkommentiert stehen lassen nie.
Woran man merkt, dass es fertig ist
Nicht daran, dass ich die Doku für gut halte, ich habe den Kontext im Kopf, den der Leser nicht hat. Sondern daran, dass ein Fremder ohne Vorwissen damit arbeiten kann. Geschrieben ist so wenig ein Beweis wie HTTP 200 ein Beweis für eine zugestellte Nachricht ist. Ich schicke deshalb einen kontextfreien Test mit den echten Fragen los. Was der findet, ist der Befund. „Ist doch alles dokumentiert“ ist keine Gegenrede.