Architekturdokumentation, die nicht verrottet
Jedes Unternehmen hat dieses Wiki: liebevoll begonnen, feierlich verlinkt, seit achtzehn Monaten nicht angefasst. Irgendwann beschreibt es ein System, das es so nicht mehr gibt. Und ab dem Tag, an dem die Doku zum ersten Mal lügt, liest sie niemand mehr. Das ist der eigentliche Schaden: nicht die veraltete Seite, sondern der Vertrauensverlust, der alle anderen Seiten mit entwertet.
Der Reflex „wir müssen disziplinierter dokumentieren" verfehlt die Ursache. Doku verrottet nicht, weil Menschen faul sind, sondern weil nichts sie daran erinnert, dass sie verrottet. Es fehlt die Rückkopplung. Die lässt sich einbauen, auf mehreren Ebenen: bei der Ablage, bei der Art der Inhalte, bei den Diagrammen und zuletzt bei der Frage, wie man Verrottung überhaupt bemerkt.
Doku wohnt im Repository
Architekturdokumentation gehört neben den Code, nicht in ein Nachbarsystem. Bei mir heißt das: arc42 als AsciiDoc, ein Kapitel pro Datei, versioniert im selben Repository, geändert im selben Pull Request wie der Code, den die Änderung betrifft. Das klingt unspektakulär, ist aber die Voraussetzung für alles Weitere: Nur was in Git liegt, hat eine Änderungshistorie, und nur mit Änderungshistorie lässt sich Verrottung überhaupt messen.
Entscheidungen dokumentieren, nicht Zustände
Der schnellste Weg zu veralteter Doku ist, möglichst viel Ist-Zustand zu beschreiben, denn der ändert sich ständig. Etwas Zustandsbeschreibung braucht jede Architekturdoku, aber sie ist ihr verderblicher Teil und sollte so klein wie möglich bleiben. Entscheidungen dagegen bleiben wahr: Warum wir uns damals so entschieden haben, stimmt auch dann noch, wenn die Entscheidung längst revidiert ist.
Deshalb sind Architecture Decision Records das Rückgrat: ein kurzes Dokument pro Entscheidung, mit Kontext, erwogenen Optionen und Konsequenzen. Zwei Details machen den Unterschied. Erstens werden ADRs nie gelöscht, nur abgelöst: Der Status wandert von „vorgeschlagen" über „angenommen" zu „abgelöst durch ADR-0017", und die Historie bleibt lesbar. Zweitens darf ein ADR seine eigene Ablösebedingung nennen: „Wenn der erste kontextübergreifende Anwendungsfall kommt, wird diese Entscheidung neu bewertet." Das Dokument kündigt seine Verfallsbedingung selbst an, statt still zu veralten.
Die Lösungsstrategie im arc42-Kapitel 4 bleibt dabei bewusst dünn: eine Tabelle mit Entscheidung, Warum und Konsequenz, drei Spalten, wenige Zeilen. Wo ein ADR existiert, liefert es die Tiefe.
Diagramme sind Quelltext
Ein Diagramm, das als Bild exportiert wurde, ist im Moment des Exports tot. Diffen und Reviewen sind damit unmöglich, und aus welcher Werkzeug-Datei es stammt, weiß hinterher niemand mehr. Deshalb: Diagramme als Code, im Repository, neben dem Kapitel, das sie einbindet. Für Strukturbilder hat sich das C4-Modell bewährt, hier als PlantUML:
@startuml
!include <C4/C4_Container>
Person(kunde, "Kunde", "Kauft im Onlineshop ein")
System_Boundary(shop, "Shop-Plattform") {
Container(storefront, "Storefront", "Shopware 6", "Katalog, Warenkorb, Checkout")
Container(pim, "PIM", "Akeneo", "Produktdaten pflegen und anreichern")
Container(suche, "Suche", "OpenSearch", "Produktsuche und Facetten")
}
System_Ext(erp, "ERP", "Bestände, Preise, Aufträge")
Rel(kunde, storefront, "kauft ein", "HTTPS")
Rel(pim, storefront, "publiziert Produktdaten", "Message Queue")
Rel(storefront, suche, "indexiert, fragt an", "HTTP")
Rel(storefront, erp, "meldet Aufträge", "REST")
@endumlDaraus macht die Build-Pipeline über einen Kroki-Dienst dieses Bild:
Ändert sich die Architektur, ändert sich eine Textdatei, und der Reviewer sieht im Diff genau, welcher Pfeil dazukam. Das Diagramm kann gar nicht mehr heimlich veralten, es steht im selben Pull Request zur Diskussion wie der Code.
Drift messen statt hoffen
Der Baustein, der bei mir am meisten verändert hat, ist banal: Jedes ADR und jedes Kapitel bekommt einen maschinenlesbaren Geltungsbereich, eine Liste der Code-Pfade, die es beschreibt. Dann lässt sich Verrottung ausrechnen. Ist der Code eines Bereichs deutlich jünger als sein Kapitel, etwa um mehr als zwei Sprints, meldet ein Check: Hier ist der Code der Doku davongelaufen.
Der Datumsvergleich hat eine Lücke: Führt eine neue Anforderung ein externes System ein, das im Kontextkapitel fehlt, bleiben die Dateien unverändert. Deshalb gehört eine zweite, inhaltliche Prüfung dazu: den Backlog gegen die Doku halten und fragen, was dort auftaucht, das hier fehlt. In einem realen Lauf fand diese Prüfung unter anderem ein Übergangssystem, das im Kontextkapitel wie das Zielsystem klang, und eine neue Umgebung, die in der Risikoliste fehlte. Vier Funde, drei sofort behoben, einer bewusst vertagt.
Wichtig ist die Dosierung: Drift ist eine Warnung, kein Stoppschild. Ein Release darf mit dokumentierter Drift ausgeliefert werden. Aber sie steht im Protokoll, und beim nächsten Mal fragt jemand nach.
Doku, die sich selbst beweist
Am meisten Vertrauen verdient Dokumentation, die mit der Realität verdrahtet ist. Qualitätsanforderungen formuliere ich als messbare Szenarien, und jedes Szenario verweist namentlich auf den automatisierten Test oder die Pipeline-Stufe, die es prüft: Antwortzeit im 95. Perzentil unter 200 Millisekunden, geprüft im nächtlichen Lasttest. Wer das Kapitel liest, kann jede Behauptung nachprüfen. Und die Risiko- und Schuldenliste in Kapitel 11 ist kein Friedhof, sondern ein Arbeitsvorrat: Jede Schuld hat ein Abbaukriterium, an dem sie wieder vorgelegt wird.
Ob das alles funktioniert, zeigt eine einzige Frage im Team: „Würdet ihr auf Basis der Doku eine Architekturentscheidung treffen, ohne vorher in den Code zu schauen?" Wenn ja, lebt sie. Wenn alle erst nachsehen wollen, ist sie schon tot, egal wie schön sie aussieht.
Klingt nach deinem Thema? Schreib mir. Im Erstgespräch klären wir unverbindlich, ob und wie ich helfen kann.