Seit Lektion 4.1.1 schreiben Sie Dokumentation: eine Bestandsaufnahme, Qualitätsziele, ADRs, ein C4-Modell, Kontexte, ein Bedrohungsmodell, eine Rechtetabelle, eine Kostenrechnung, Notfallproben. Jedes Stück entstand in seiner Lektion und war dort richtig. Inzwischen hat sich der Code darunter bewegt: Module kamen dazu, Grains, Mandanten, Stamps. In dieser Lektion wird aus den Stücken eine Dokumentation, die stimmt, die man in einer bestimmten Zeit lesen kann und die nicht wieder veraltet, ohne dass es jemand merkt.

Die Messlatte steht seit der Gliederung dieses Moduls fest: Eine fremde Person liest 30 Minuten in docs/ und kann danach erklären, wie ein Angebot durch das System läuft. Geprüft wird das in Lektion 4.9.6 von einer Person aus Ihrem Kreis, und in 4.9.7 lesen Sie dieselben Seiten mit der Checkliste des Architektur-Reviews.

Für wen Sie schreiben

Architekturdokumentation hat mehrere Leserinnen, und jede will etwas anderes:

Wer Will wissen Liest zuerst
eine neue Entwicklerin im Team wo was liegt, wie ein Ablauf durch die Module geht, welche Regeln gelten Einstieg, Container, Komponenten, der Weg eines Angebots
das Architektur-Review in 4.9.7 warum es so gebaut ist und was es kostet ADRs, Qualitätsszenarien mit Nachweis, Kosten
der Betrieb was läuft wo, was tun im Notfall Deployment, Notfallplan und Proben, Rechtetabelle
die Sicherheit wo die Grenzen sind und was sie schützt Vertrauensgrenzen, Bedrohungsmodell, Rechtetabelle
die Fachperson ob das System ihre Abläufe richtig abbildet Kontext, Glossar, Kontexte

Sie schreiben nicht fünf Dokumentationen, sondern eine mit fünf Wegen hinein. Die Wege stehen im Einstieg, docs/README.md. Microsofts Leitfaden für Architektinnen und Architekten nennt dieses Bündel eine Entwurfsbeschreibung (architecture design specification): Diagramme, Entscheidungen, nichtfunktionale Anforderungen, Notfallplan, Sicherheit, alles mit Zustand und Querverweisen. Die Kladde hat das alles schon, verteilt. Jetzt bekommt es eine Ordnung.