Ich habe ja mal erzählt, dass ich ein Faible für Architekturdokumentation habe und ich freue mich sehr, dass wir immer wieder die Möglichkeit haben, unsere Kunden bei der (Nach-)Dokumentation der Architektur ihrer Systeme zu unterstützen. Dabei fällt mir immer wieder auf, dass es vielen Leuten schwerfällt, eine gute Architekturdokumentation zu schreiben. Der Start ist besonders schwierig, denn viele befällt dabei der Horror Vacui – die Angst vor dem weißen Blatt.

Glücklicherweise gibt es ja gute Startpunkte, beispielsweise das populäre Arc42-Template, das einem schon eine hilfreiche Struktur mit jeweils vorgeschlagenen Inhalten vorgibt:

• Einführung und Ziele: Eine kurze Übersicht über die wichtigsten Anforderungen, Qualitätsziele und Stakeholder des Systems
• Randbedingungen: Einschränkungen die zu beachten sind
• Kontextabgrenzung: Abgrenzung von System zum umgebenden Kontext mit benachbarten Systemen und Nutzer:innen
• Lösungsstrategie: Die wichtigsten Entwurfsentscheidungen und des zentralen Lösungsansatzes
• Bausteinsicht: Eine hierarchische Zerlegung des Systems in interagierende Bausteine
• Laufzeitsicht: Das Verhalten des Systems für die wichtigsten Funktionalitäten und Prozesse
• Verteilungssicht: Die Verteilung der Deployment-Artefakte auf Rechenknoten und Infrastruktur-Komponenten
• Querschnittliche Konzepte: Übergreifende, generelle Prinzipien und Lösungsansätze
• Architekturentscheidungen: Wichtige, teure oder kritische oder riskante Architekturentscheidungen
• Qualitätsanforderungen: Qualitätsanforderungen in Form von Szenarien
• Risiken und technische Schulden: Bekannte Risiken und angehäufte technische Schulden
• Glossar: Wichtige Domänenbegriffe und technische Begriffe, die Stakeholder kennen sollten

Die Verwendung eines solchen Templates hat für die Ersteller:in der Dokumentation viele Vorteile: Man bekommt einen vorgefertigten Startpunkt, Hilfestellung um an die wichtigsten Aspekte zu denken, es gibt eine fertige Struktur und vor allem hilft es, die Angst vor dem leeren Blatt zu überwinden.

Und wenn man sie als Startpunkt versteht, sind solche Templates super und gegen ihre Verwendung auch nichts einzuwenden. Wir sehen in unseren Projekten aber immer wieder eine totale Überfokussierung auf solche Templates und das eigentliche Ziel der Erstellung der Dokumentation und dessen Verwendung tritt in den Hintergrund. Konkret bedeutet das:

• Das hauptsächliche Augenmerk liegt darauf, dass einfach alle Kapitel ausgefüllt sind.
• Die Kernkapitel Building Block View, Runtime View und Deployment View werden mit einigem Inhalt befüllt, außen herum finden sich weniger Informationen.
• Die Diagramme in den Views zeigen bei weitem nicht alle relevanten Informationen. Eher sieht es so aus, als müsse jede View halt ein oder zwei Diagramme beinhalten.
• Die eingefügten Inhalte transportierten nur die rudimentärsten Informationen zur Beschaffenheit der Architektur des Systems.
• Häufig ersetzen allgemeine Erklärungen zu Mustern, Ansätzen und Technologien die eigentlich notwendigen Informationen, die spezifisch sind für das System.

Damit verkommt die Architekturdokumentation zum Cargo-Kult nach Lehrbuch. Das ist schade, denn der Mehrwert für die Leser:innen der Dokumentation ist damit massiv eingeschränkt.

Wenn wir die Architektur eines Systems dokumentieren, lassen wir uns deswegen viel stärker von den Spezifika des jeweiligen Systems leiten, als von einer starren und allgemeinen Vorlage. Überlegt doch einfach mal, was ihr jemandem, der davon keine Ahnung hat erzählen würdet, wie Euer System funktioniert. Was macht Euer System aus, was ist besonders? Da werdet ihr bei unterschiedlichen Systemen zu einer sehr unterschiedlichen Strukturierung und Inhalten kommen. Und die ist vor allem davon geprägt, dass man eine gute Story mit rotem Faden erzählt, die man gut verstehen und der man gut folgen kann. Und diese Inhalte werden dann natürlich mit passenden Views und Diagrammen transportiert. Sorgfältig ausgewählt, um die Message zu transportieren.

Natürlich nutzen wir auch eine immer wiederkehrende Grundstruktur (ähnlich zu Arc42), die wir aber nach Bedarf anpassen und direkt unter Top Level wird es dann immer sehr schnell spezifisch. Hier ein (anonymisiertes und vereinfachtes) Beispiel:

• Einleitung und Zielstellung
• Geschäftlicher Kontext
• Architekturtreiber
• Kontextabgrenzung
• Grundlegende Architekturentscheidungen und Lösungsansatz
• System-Dekomposition
  • Zentrale Fachliche Konzepte
    • Zentrales Element XXX
    • Team-übergreifende Zusammenarbeit
  • Subsysteme und Interaktionen
  • Integration mit Altsystem YYY
  • Interne Strukturierung der ZZZ-Services
  • Core Datenmodell
  • Datenhaltung: Datenbank und Repositories
  • Code Organisation
  • CoreLibs Modul
  • Deployment
  • Betrieb: Monitoring und Backup-Strategie
  • Verwendete Technologien
• Qualitäts- und Querschnittskonzepte
  • Offline-Fähigkeit
  • Security
    • Authentifizierung
    • Autorisierung
    • Verschlüsselung
  • Audit Trail der Geschäfts-Transaktionen
  • Erweiterbarkeit: Anbindung neuer Datenquellen
  • Logging
  • Exception Handling
  • Internationalisierung
  • Skalierbarkeit
• Risiken und Technische Schulden
• Vision für die Zukunft

Das Beispiel soll nur dazu dienen, einen Eindruck zu bekommen und lässt sich natürlich nicht 1:1 übertragen; klar, ist ja auch spezifisch für das System.

Aber weil „Mach es sinnvoll und spezifisch!“ als Methode auch nur eingeschränkt hilfreich ist, sind hier noch ein paar Prinzipien, von denen wir uns bei der Erstellung einer Dokumentation leiten lassen:

• Beschreibe die Kern-Entscheidungen: Es gibt einige wenige Entscheidungen, die zentral für das System sind. Beschreibe diese direkt am Anfang, so dass man ein initiales Bild vom Lösungsansatz bekommt.
• Kontext vor Interna: Beschreibe erstmal das Außenrum und mache den Kontext klar, bevor du in die internen Details abtauchst.
• Runtime vor Devtime: Beschreibe zuerst, wie sich das System verhält, während es läuft, bevor du beschreibst, wie es gebaut wurde.
• Systemzerlegung vor Qualitätskonzepten: Beschreibe zuerst wie das System grundsätzlich aufgebaut ist und dann wie die querschnittlichen Konzepte darauf wirken
• Fokus auf Daten: Daten sind häufig zu unterrepräsentiert. Berücksichtige Datenmodelle, Datenhaltung, Datentransport, etc.
• Berücksichtige Qualitätsattribute der Entwicklungszeit: Entwicklungszeit-Qualitäten sind häufig unterrepräsentiert. Denke auch mal an Flexibilität, Erweiterbarkeit, Testbarkeit, etc.
• Mache gute Bilder: Bilder tragen enorm zur Verständlichkeit bei. Erstelle Diagramme, um die wichtigsten Sachverhalte zu illustrieren. Achte darauf, dass die Diagramme lesbar, fokussiert, ansprechend und konsistent zu anderen Diagrammen sind.

Wir hoffen, dass diese Prinzipien auch Euch beim Schreiben eurer Architekturdokumentation weiterhelfen. Weitere Ideen und Tipps findet Ihr in unserem Vortrag „Meisterwerk oder Groschenroman? – 7 Anti-Patterns und Tipps für gute Architektur-Dokumentationen„.

Und weil es einerseits viel Bedarf gibt und es andererseits einfach ein schönes Thema ist, starten wir hiermit eine Reihe mit Tipps und Tricks zu Architekturdokumentation. Also, stay tuned!