Architektur dokumentieren und kommunizieren

Willkommen zu Kapitel 4: Architektur dokumentieren und kommunizieren. Dieses Kapitel zeigt, wie man eine Softwarearchitektur so beschreibt, dass die richtigen Menschen sie verstehen und die Beschreibung zutreffend bleibt. Es ist durchgehend praxisnah und nutzt eine Essenslieferplattform als durchgängiges Beispiel, sodass Sie jede Technik am selben System vergleichen können.

Eine Architektur, die nur in den Köpfen weniger Menschen existiert, ist fragil. Niemand außerhalb des Raums kann sie prüfen, Neue im Team können sie nicht erlernen, ein Prüfer kann sie nicht kontrollieren, und sie geht mit den Menschen, die sie kennen. Bei Dokumentation kann man leicht in beide Richtungen danebenliegen. Teams, die zu wenig schreiben, verlieren die Gründe hinter ihrer Struktur und führen immer wieder dieselben Diskussionen. Teams, die zu viel schreiben, produzieren Wikis, denen niemand traut. Der Leitgedanke des Kapitels ist also einfach: Schreiben Sie für den Leser. Entscheiden Sie, wer jedes Stück Dokumentation nutzt und was diese Person braucht, schreiben Sie das knapp und präzise auf, und schreiben Sie nichts anderes.

Das Kapitel richtet sich an Entwickler, Architekten und technische Leitungen. Es baut auf Kapitel 1 bis 3 auf: auf den Entscheidungen und Strukturen, die nun beschrieben werden müssen. Die Abschnitte eins Punkt fünf zu Stakeholdern und Anliegen und eins Punkt sechs zu Entscheidungen und Abwägungen sind besonders nützliche Grundlagen. Und es führt zu Kapitel 5, das den Katalog der Architekturstile beginnt, beschrieben mit den Werkzeugen, die Sie hier lernen.

Das Kapitel hat acht Abschnitte. Abschnitt vier Punkt eins fragt, für wen Dokumentation gedacht ist und wie man entscheidet, was es verdient, aufgeschrieben zu werden. Die kurze Antwort: Schreiben Sie von Hand auf, was der Code nicht sagen kann, und generieren Sie, was der Code bereits aussagt. Abschnitt vier Punkt zwei führt den zentralen Gedanken ein, dass ein einzelnes Diagramm nie genügt. Eine Architektur wird durch mehrere Sichten beschrieben, von denen jede die Anliegen bestimmter Stakeholder beantwortet. Abschnitt vier Punkt drei macht daraus den am weitesten verbreiteten praktischen Ansatz, Simon Browns C4-Modell, mit vier Zoomstufen und einigen Notationsregeln, die Diagramme selbsterklärend machen. Abschnitt vier Punkt vier behandelt die Teile der Unified Modeling Language, kurz UML, die Architekten noch verwenden, etwa Sequenz- und Zustandsdiagramme, und wann sich ihre Präzision lohnt.

Dieses Diagramm aus Abschnitt vier Punkt eins hilft Ihnen zu entscheiden, wie Sie eine Information dokumentieren. Die senkrechte Achse fragt, ob sie sich aus dem Code ableiten lässt. Die Achse unten fragt, wie oft sie sich ändert. Oben links: Dinge, die der Code nicht sagen kann und die sich selten ändern. Kontext und Abgrenzung, Qualitätsziele und Entscheidungen mit ihren Gründen. Schreiben Sie diese von Hand auf, und bewahren Sie sie auf. Oben rechts: Dinge, die sich öfter ändern, etwa Container- und Deployment-Sichten. Halten Sie sie neben dem Code, und prüfen Sie sie bei jeder Änderung. Unten rechts: was der Code bereits aussagt und sich oft ändert, etwa Klassendiagramme und API-Referenzen. Generieren Sie diese in der Pipeline. Schreiben Sie sie nie von Hand. Und unten links: Dinge, die man im Code lesen kann und die sich selten ändern, wie der Technologie-Stack oder die Build-Befehle. Ein kurzer Verweis in einer README-Datei genügt.

Hier ist die erste Ebene des C4-Modells aus Abschnitt vier Punkt drei: ein Systemkontextdiagramm für die Essenslieferplattform. Oben stehen die drei Arten von Menschen, die sie nutzen: Kunden, Restaurantpersonal und Kuriere. Jeder Pfeil ist mit dem beschriftet, was sie tun. In der Mitte steht die Plattform selbst, als ein einziger Kasten. Sie nimmt Bestellungen an, kassiert die Zahlung, weist Kuriere zu und hält alle auf dem Laufenden. Darunter stehen die externen Systeme, von denen sie abhängt: ein Zahlungsanbieter, ein Kartendienst und Push-Dienste. Auf dieser Ebene gibt es keine Technologien oder Protokolle. Die kommen erst auf der nächsten Zoomstufe, den Containern. Und beachten Sie die Legende. Jedes C4-Diagramm hat einen Titel und eine Legende, damit es sich selbst erklärt.

Diagramme zeigen Struktur, aber sie zeigen selten das Warum. Abschnitt vier Punkt fünf behandelt Architecture Decision Records, kurz ADRs: kurze, datierte Aufzeichnungen zu je einer Entscheidung, mit einem vollständig ausgearbeiteten Record für die Lieferplattform. Abschnitt vier Punkt sechs zeigt, wie eine Vorlage wie arc zweiundvierzig der ganzen Beschreibung eine Standardgliederung gibt, sodass Schreibende wissen, was sie abdecken, und Lesende, wo sie nachsehen. Abschnitt vier Punkt sieben geht das Problem an, an dem die meiste Dokumentation scheitert: das Veralten. Er behandelt Diagramme als Text, das Veröffentlichen von Dokumentation aus der Build-Pipeline und die Gewohnheiten der Verantwortung, die sie zutreffend halten. Abschnitt vier Punkt acht wendet sich von Dokumenten den Menschen zu: die Botschaft auf Führungskräfte, Entwickler, Betrieb, Sicherheitsfachleute und Prüfer zuschneiden, Abwägungen erklären und Konsens herstellen, wenn Menschen uneins sind.

Jede Technik in diesem Kapitel dient einem Ziel: einem gemeinsamen, zutreffenden Verständnis des Systems unter den Menschen, die es bauen, betreiben, bezahlen und von ihm abhängen. Kleine, aktuelle Dokumentation mit klarer Verantwortung, die neben dem Code liegt, schlägt ein umfassendes Dokument, dem niemand traut. Wenn Sie sich also eine Frage aus diesem Kapitel merken, dann diese: Wer wird das lesen, und was wird er damit tun?

Sie können die Abschnitte der Reihe nach lesen oder gezielt die Technik aufschlagen, die Sie heute brauchen. Das ganze Kapitel zu lesen dauert etwa drei Stunden. Vergleichen Sie dabei, wie jede Technik dieselbe Essenslieferplattform beschreibt: als Kontextdiagramm, Containerdiagramm, Sequenz- und Zustandsdiagramme, Entscheidungsdokument und einseitige Zusammenfassung. Jeder Abschnitt endet mit einigen Fragen zur Selbstkontrolle. Beantworten Sie sie im Kopf, bevor Sie nachsehen. Wenn Sie so weit sind, machen Sie den freiwilligen Kapiteltest: zwanzig Multiple-Choice-Fragen und zwei schriftliche Antworten, in etwa fünfundvierzig Minuten. Die Bestehensgrenze liegt bei achtzig Prozent.

Das ist die Übersicht über Kapitel 4. Beginnen Sie mit Abschnitt vier Punkt eins, in dem wir uns ansehen, für wen Dokumentation gedacht ist und wie viel davon sich zu schreiben lohnt. Bis gleich.