Write-only Documents

Zum Quell der architektonischen Freuden gehört für die meisten Architekten das Dokumentieren nicht. Liegt das daran, dass kein Projektbeteiligter Architekturdokumente nutzt? Oder eher daran, dass diese sich entweder lesen wie Telefonbücher oder wie Grimms Märchen? Ich begebe mich auf Spurensuche.

Als ich vor einer gefühlten Ewigkeit ein Architekturdokument zu Windows NT konsumieren musste, hatte ich die schlimmsten Vorahnungen. Ein leidvoller Weg voller Entbehrungen stünde mir bevor, dachte ich zumindest. Beim Lesen der Dokumentation änderte sich aber das Bild völlig. Die Autoren hatten den Weg von den Anforderungen über Entwurfsrichtlinien bis hin zu der eigentlichen Architektur klar und verständlich und bisweilen sogar unterhaltsam strukturiert. Die Schönheit der Architektur spiegelte sich auch in der Architekturdokumentation wider, die eine Top-Down-Struktur aufwies, verschiedene Lesergruppen berücksichtigte und nur die Information enthielt, die der Nutzer benötigt. Und das genau an den Stellen, an denen ich die Information erwartet hätte. Hinterher besaß ich ein tiefgreifendes Wissen über das neue Betriebssystem.

Leider hat dieses Erlebnis einen sehr großen Seltenheitswert. Normalerweise sind Architekturdokumente reine Theorie, nicht up to date, enthalten auf engstem Raum eine hohe Informationsdichte oder lassen vermeintlich Unwichtiges weg – und haben meistens einen maximalen Grad an Entropie. Zwar gibt es durchaus Reviews von Architekturdokumenten, aber die führen meistens zum weiteren Aufblähen derselben. Daher denke ich oft, dass es ein Leichtes wäre, Wettbewerber zu schädigen, wenn man ihnen die eigene Architekturdokumentation zuspielte.

Und vergessen wir nicht diejenigen agilen Entwickler, für die der Code das Architekturdokument darstellt. Wie ein Vertreter dieser Spezies eine Software mit mehreren Hundertmillionen Zeilen anhand der Codebasis verstehen und pflegen will, erschließt sich mir nicht. Ganz abgesehen davon, dass Architekturdokumentation nicht nur den Entwickler adressiert.

Vor geraumer Zeit habe ich mir eine Top 10 der Best Practices für Architekturdokumentation überlegt. Diese resultieren daraus, Architektur als eine Folge von architektonischen und technologischen Entscheidungen zu betrachten:

1. Dokumente benötigen Produktqualität wie auch alle anderen Entwicklungsartefakte. Daher sollten sie Gegenstand von Versionierung, Change Management und Refactoring sein.
2. Dokumente sollen die Architektur aus der Brille der Lesergruppen erläutern.
3. Unnötige Wiederholungen sollte das Dokument vermeiden (DRY).
4. Ein Problemdomänenmodell sollte die wichtigsten Komponenten der Problemdomäne inklusive ihrer Abhängigkeiten als Teil der Architekturdokumentation beschreiben. Das übliche Glossar hat nur begrenzten Nutzen.
5. Alle Dokumente sollten dasselbe Template nutzen, um unliebsame Überraschungen für die Leser zu vermeiden. Selbstredend sollte das Template den Bedürfnissen der eigenen Organisation entgegenkommen.
6. Nicht nur das "Was" ist zu dokumentieren, sondern auch das "Wie" und das "Warum". Und das gilt für alle Architekturentscheidungen. Das bloße Generieren von UML-Diagrammen aus Code ist daher unzureichend.
7. Ein Dokument sollte aktuell sein, ohne aber stündlichen Änderungen zu unterliegen. Die Dauer eines Sprints lässt sich als Zeitlänge zwischen Updates nutzen.
8. Für jedes Architekturdokument muss es einen eindeutigen Ansprechpartner geben, der für die inhaltliche Qualität verantwortlich ist.
9. Ein Dokument sollte als Daumenregel maximal 50 Seiten haben. Information über Subsysteme, NFRs wird daher in eine Hierarchie weiterer Dokumente ausgelagert.
10. Dokumente müssen regelmäßig qualitätsgeprüft werden. Am besten von der Zielgruppe der Dokumente.

Nicht nur die Dokumentation der Entscheidungen ist interessant, sondern auch die Dokumentation dessen, was für die Entscheidungen wichtig war, aber keinen Platz im Architekturdokument fand. Ich denke zum Beispiel an verworfene Lösungsalternativen, viel diskutierte Entscheidungen, oder unerwähnte Einflussfaktoren. Derartige Faktoren landen bei mir neben den Protokollen der Treffen in einem "Architekturtagebuch", das ich als informelles Dokument pflege. Ganz gut hat sich ein Wiki-Ansatz dafür bewährt.

Vielleicht ist die wichtigste Regel bei der Architekturdokumentation aber die, das Dokument so zu entwerfen, wie man es selbst gerne als Architekt, Entwickler, Product Owner, DevOp .... zur Verfügung gestellt bekäme. ()