Architektur dokumentieren und weiterentwickeln

Architektur dokumentieren und weiterentwickeln

0:00 Dokumentation hat in unserer Branche einen zweifelhaften Ruf, und dafür gibt es Gründe: Zu viele von uns haben Ordner mit Dokumenten gesehen, die einen Zustand von vor drei Jahren beschreiben. Trotzdem gilt: Eine Architektur, die niemand erklären kann, ist keine Architektur, sondern ein Zustand. In diesem Modul geht es deshalb um das Gegenteil von Vollständigkeit — um wenige, gezielte Mittel: eine Abstraktionsleiter für Diagramme, eine Gliederung, ein Format für Entscheidungen und automatisierte Prüfungen.

Architektur dokumentieren und weiterentwickeln

0:29 Vier Kapitel. Zuerst C4 als Abstraktionsleiter für Diagramme — die Antwort auf die beliebigen Kästen und Pfeile, die man kennt. Dann arc42 als Struktur für das, was um die Diagramme herum gehört. Drittens Architecture Decision Records, mit denen wir schon mehrfach gearbeitet haben, jetzt genauer. Und zum Schluss evolutionäre Architektur: Fitness Functions und das Strangler-Fig-Muster.

Verständliche Architekturdokumentation

0:55 Beginnen wir mit Diagrammen. Sie sind das meistgenutzte und am schlechtesten gepflegte Werkzeug der Architekturkommunikation — und das liegt fast immer an einer einzigen fehlenden Festlegung. C4 steht für vier hierarchische Abstraktionsebenen: System Context, Container, Component und Code. Das Bild dahinter ist eine Landkarte mit Zoomstufen — von der Übersichtskarte bis zum Straßenplan. Auf jeder Stufe zeigt man eine Sache, und man mischt die Stufen nicht.

1:23 Wichtig ist noch der letzte Satz: Das Modell ist notationsunabhängig und werkzeugagnostisch. Es schreibt Ihnen keine Symbolsprache vor und verlangt kein bestimmtes Programm. Es verlangt nur, dass Sie sagen, auf welcher Stufe Sie gerade sind. Die rechte Spalte ist der praktische Nutzen: Jede Ebene hat ein anderes Publikum.

1:43 Die Kontextebene können Sie einer Fachabteilung zeigen, die Containerebene der Technik und dem Betrieb. Die Komponentenebene interessiert nur das Team des jeweiligen Containers, und die Codeebene brauchen Sie fast nie — sie steht ohnehin im Code. Merken Sie sich die Definition eines Containers: etwas, das läuft. Kein Ordner, kein Modul, kein Docker-Container zwangsläufig.

2:06 Die Fußzeile ergänzt die Diagrammtypen für Abläufe und Verteilung. Hier liegt die eigentliche Erkenntnis. Fast jedes schlechte Architekturdiagramm hat dieselbe Krankheit: Es mischt Ebenen. Ein Kästchen ist ein Dienst, das daneben eine Klasse, das dritte ein Server — und deshalb kann niemand die Beziehungen deuten. Der letzte Punkt ist mein wichtigster Ratschlag dazu: Wer alle vier Ebenen pflegt, pflegt am Ende keine. Beschränken Sie sich auf Kontext und Container.

2:35 Diese beiden bleiben über Jahre stabil und beantworten die meisten Fragen. Der dritte Punkt ist der stillste: Die Farben bedeuten etwas, das nur der Autor kennt. Nach einem halben Jahr weiß er es selbst nicht mehr. Eine Legende kostet fünf Minuten. Und der vierte Punkt beschreibt das Ende jedes Diagramms — es wird einmal gezeichnet und nie mit dem Code abgeglichen.

2:57 Genau dagegen hilft der Gedanke, der im letzten Kapitel wiederkommt: Was nicht geprüft wird, veraltet. Diagramme, die neben dem Code liegen und mit ihm versioniert werden, haben immerhin eine Chance.

Strukturierte Dokumentation

3:10 C4 liefert die Bilder. Was aber gehört an Text darum herum — und in welcher Reihenfolge? Dafür gibt es eine bewährte Gliederung, die Ihnen diese Frage abnimmt. arc42 beantwortet eine überraschend praktische Frage: Wohin gehört diese Information? Ohne Gliederung entsteht Dokumentation als loser Stapel, in dem jeder etwas anderes zuerst schreibt.

3:33 Mit Gliederung weiß jeder, wo die Qualitätsziele stehen und wo die Verteilungssicht. Der letzte Satz fasst das Zusammenspiel: C4 liefert die Diagramme, arc42 den Rahmen darum. Die beiden sind keine Konkurrenten, sondern ergänzen sich — das wird häufig verwechselt. Die ersten sechs Abschnitte führen von den Zielen bis zur Laufzeitsicht. Schauen Sie auf Abschnitt eins: Grundanforderungen, besonders die Qualitätsziele.

4:00 Das ist genau das Ergebnis Ihrer Übung aus Modul zwei — es hat hier seinen festen Platz. Abschnitt fünf, die Bausteinsicht, ist laut Fußzeile meist der umfangreichste Teil und zugleich der, der am schnellsten veraltet. Das ist ein Argument dafür, ihn bewusst grob zu halten: Was sich wöchentlich ändert, gehört nicht in ein Dokument.

4:20 Die zweite Hälfte. Abschnitt neun nimmt die Architekturentscheidungen auf, über die wir gleich sprechen. Abschnitt elf ist der ehrlichste des ganzen Templates: Risiken und technische Schulden. Ein Dokument, das diesen Abschnitt leer lässt, beschreibt kein reales System. Und Abschnitt zwölf, das Glossar, ist der am meisten unterschätzte — dazu gleich mehr.

4:42 Die Fußzeile nennt die Arbeitsweise, die das alles zusammenhält: Docs as Code, also neben dem Quellcode, versioniert und im selben Lauf geprüft. Dieser Punkt ist mir wichtig, weil Vorlagen einen Vollständigkeitsdruck erzeugen. Leere Abschnitte sind schlechter als fehlende — sie täuschen vor, dass jemand nachgedacht hat.

5:01 Was sich aus dem Code ergibt, gehört nicht in ein zweites Dokument, denn dann haben Sie zwei Wahrheiten. Und der letzte Punkt: Das Glossar ist unterschätzt. Wenn Fachbereich und Technik dasselbe Wort verschieden benutzen, entstehen Fehler, die niemand als Verständnisproblem erkennt — sie sehen aus wie Programmierfehler.

5:20 Der zweite Punkt ist das klassische Projektmuster: Dokumentation entsteht am Ende und beschreibt einen Stand von vor sechs Monaten. Der dritte ist der, der im Ernstfall schadet — die Verteilungssicht zeigt eine Umgebung, die es nicht mehr gibt, und jemand trifft nachts eine Entscheidung auf dieser Grundlage. Wenn Sie einen Abschnitt nicht pflegen können, schreiben Sie hinein, wann er zuletzt stimmte. Eine ehrliche Datumsangabe ist mehr wert als eine gepflegte Fassade.

Architecture Decision Records

5:47 Damit zu dem Format, das wir in diesem Seminar schon mehrfach benutzt haben. Jetzt schauen wir genauer hin — denn ein schlechter ADR ist leicht geschrieben und wertlos. Der zentrale Begriff steht im zweiten Satz: eine architektonisch bedeutsame Anforderung, also eine mit messbarer Wirkung auf Architektur und Qualität. Das ist dieselbe Idee wie der Architekturtreiber aus Modul zwei, nur von der anderen Seite betrachtet. Und ein ADR hält nicht fest, was gilt — das steht im Code.

6:17 Er hält fest, warum es gilt: mit Begründung, mit Abwägungen, mit Konsequenzen. Diese drei Dinge gehen sonst verloren, und zwar innerhalb weniger Monate. Fünf Schritte, von denen ich zwei hervorheben möchte. Schritt zwei verlangt Alternativen, jede mit ihrem eigentlichen Nachteil — nicht mit einem Scheinnachteil, der die gewählte Option gut aussehen lässt.

6:39 Und Schritt fünf ist der, der ADRs von Grabsteinen unterscheidet: der Anlass, bei dem neu zu entscheiden wäre. Damit wird aus einer Festlegung etwas Überprüfbares. Die Fußzeile ergänzt: Gesammelt werden ADRs in einem Decision Log — ein einzelner Eintrag ohne Sammlung wird nicht gefunden und damit nicht gelesen. Drei Formate, die Ihnen begegnen werden. Das Nygard-Format ist knapp und hat sich als Einstieg durchgesetzt.

7:04 Das Y-Statement fasst die Entscheidung in einen strukturierten Satz — überraschend wirksam, weil die Kürze zum Punkt zwingt. MADR gibt eine ausführlichere Markdown-Vorlage vor. Und der letzte Punkt ist der, auf den es ankommt: Welches Format Sie wählen, ist weniger wichtig als die Gewohnheit, überhaupt zu schreiben. Ein knapper Eintrag, der existiert, schlägt eine perfekte Vorlage, die niemand ausfüllt.

7:29 Eine naheliegende Anwendung, und sie funktioniert gut — mit einer klaren Grenze. Ein Modell kann aus Ihren Notizen einen vollständigen Entwurf formulieren, kann prüfen, ob Alternativen und Konsequenzen wirklich benannt sind, und kann bestehende Einträge gegen den heutigen Code gegenlesen. Das sind alles Fleißaufgaben. Der letzte Punkt zieht die Grenze: Die Entscheidung bleibt beim Team.

7:51 Begründen heißt verantworten — und Verantwortung lässt sich nicht delegieren, auch nicht an ein sehr gutes Werkzeug. Der erste Punkt ist der häufigste: Der ADR beschreibt die Lösung, aber nicht den Anlass — und damit fehlt genau das, was in drei Jahren interessiert. Der dritte ist ein Ehrlichkeitsproblem: Die Konsequenzen sind ausschließlich positiv formuliert.

8:12 Jede Entscheidung hat unangenehme Folgen; wer sie nicht aufschreibt, verschiebt die Überraschung nur. Und der vierte ist handwerklich: Ein überholter Eintrag wird gelöscht statt auf abgelöst gesetzt. Damit verlieren Sie die Geschichte — und die ist oft das Wertvollste am Decision Log.

Evolutionäre Architektur

8:29 Zum letzten Kapitel vor dem Abschlussworkshop. Es beantwortet die Frage, wie eine Architektur über Jahre bleibt, was sie sein soll — ohne dass jemand danebensteht und aufpasst. Das Schlüsselwort steht am Ende: Architecture Fitness Functions. Der Name kommt aus der Evolutionsbiologie und meint automatisierte Prüfungen, die eine Architektureigenschaft messbar machen und im Bauprozess durchsetzen.

8:53 Das ist derselbe Gedanke, den wir bei den Modulgrenzen in Modul acht hatten, nur verallgemeinert: Jede Architekturregel, die Sie wirklich meinen, sollte prüfbar sein. Und was prüfbar ist, kann man automatisieren. Was nicht automatisiert ist, wird über die Jahre weich. Vier Beispiele, die alle realistisch sind. Abhängigkeitsregeln — das ist der modulare Monolith aus Modul acht.

9:17 Antwortzeit auf einem definierten Pfad — dafür braucht es die Messbarkeit aus Modul zwei. Schnittstellenverträge — ein Vertragstest, wie in Modul sechs besprochen. Und die Lieferkette — die Prüfungen aus Modul zehn. Das ist der Punkt, an dem dieses Seminar zusammenläuft: Aus jedem Themenfeld wird eine Regel, und die Regeln laufen alle im selben Bauprozess.

9:40 Das Bild dahinter ist eine Würgefeige: Sie wächst um einen bestehenden Baum herum, bis sie selbst trägt und der alte Baum verschwindet. Übertragen heißt das: Das neue System wächst um das alte herum, Stück für Stück, und ein Umleitungspunkt entscheidet je Aufruf, wer antwortet. Der entscheidende Vorteil steht im dritten Punkt: Jeder Schritt ist für sich nützlich und für sich zurücknehmbar.

10:02 Ein Neuschreiben auf einen Schlag hat diese Eigenschaft nicht — es ist eine einzige große Wette. Hier steckt die organisatorische Pointe des Moduls. Regeln, die im Bauprozess laufen, brauchen kein Gremium — sie wirken sofort und für alle gleich. Ein Architekturboard entscheidet dann Ausnahmen statt den Alltag, und das ist eine sinnvolle Aufgabe.

10:23 Technische Schulden gehören sichtbar in die Dokumentation, nicht in Flurgespräche. Und der letzte Punkt ist die Warnung an alle, die Regeln durchsetzen wollen: Wer Abweichungen nur verbietet, bekommt sie unbemerkt. Ein dokumentierter Ausnahmeweg ist besser als ein umgangenes Verbot. Der erste Punkt ist die häufigste Halbherzigkeit: Fitness Functions werden definiert, laufen aber nicht im Bauprozess. Dann sind sie eine Absichtserklärung.

10:49 Der zweite ist das typische Ende einer Migration — sie bleibt auf halbem Weg stehen, und beide Systeme leben weiter, mit doppeltem Betriebsaufwand. Deshalb braucht jeder Schritt seinen eigenen Nutzen. Im letzten Modul führen Sie alles zusammen: eine vollständige Zielarchitektur für Kartenwerk, mit Diagramm und mit begründeten Entscheidungen.