Warum und wie viel dokumentieren

Warum eine Architektur aufgeschrieben werden muss

Jedes System hat eine Architektur, ob sie nun jemand beschreibt oder nicht (siehe Abschnitt 1.1). Die Architekturbeschreibung ist etwas anderes: die Dokumente, Diagramme, Modelle und Entscheidungsdokumente, über die Menschen ein Verständnis dieser Architektur teilen. In einem Team von drei Personen, die zusammensitzen und jede Zeile selbst geschrieben haben, kann ein Großteil der Beschreibung in ihren Köpfen leben. Sobald das Team wächst, Menschen gehen, ein zweites Team hinzukommt, ein Prüfer auftaucht oder das System seine Autoren überdauert, wird Wissen, das nur in Köpfen existiert, zum Risiko. Ralph Johnsons Definition von Architektur als gemeinsames Verständnis der erfahrenen Entwickler enthält eine Warnung: Ein Verständnis, das nicht aufgeschrieben ist, lässt sich nur durch Gespräche teilen, und Gespräche skalieren nicht.

Documenting Software Architectures: Views and Beyond (Paul Clements und Kollegen am Software Engineering Institute, 2. Auflage, 2010) nennt drei Verwendungszwecke für Architekturdokumentation, und sie sind noch immer die klarste Art, darüber nachzudenken, warum sich der Aufwand lohnt. Sie dient der Wissensvermittlung: Sie führt neue Teammitglieder, externe Prüfer und neue Architekten in das System ein. Sie ist das wichtigste Mittel der Kommunikation zwischen Stakeholdern: Entwickler, Betrieb, Sicherheitsfachleute und Management diskutieren über das System anhand der Dokumentation, und Entscheidungen aus einem Meeting erreichen Menschen, die nicht dabei waren. Und sie ist die Grundlage für Analyse und Umsetzung: Sie sagt den Implementierenden, was sie tun dürfen und was nicht, und sie ist das, was eine Bewerterin untersucht, wenn sie fragt, ob das System seine Qualitätsziele erreichen wird (die Bewertungsmethoden aus Kapitel 11 brauchen eine Beschreibung als Arbeitsgrundlage).

Daraus folgen zwei Konsequenzen. Erstens ist Dokumentation ein Mittel, kein Zweck: Ein Dokument, das keinem dieser Zwecke dient, ist Verschwendung, wie gut es auch formatiert sein mag. Zweitens entscheidet der Leser, ob sie funktioniert hat. Eine Beschreibung, die ihr Autor vollständig findet, mit der ein Neuling aber nichts anfangen kann, ist bei der Wissensvermittlung gescheitert, und ein Diagramm, das das Betriebsteam nicht auf echte Server abbilden kann, ist bei der Analyse gescheitert.

Funktionierende Software vor umfassender Dokumentation

Das Agile Manifest (2001) nennt vier Wertepaare, eines davon lautet Funktionierende Software mehr als umfassende Dokumentation. Es wird oft als Erlaubnis zitiert, gar nicht zu dokumentieren. Vollständig gelesen, sagt das Manifest etwas Engeres. Seine Autoren erklären, dass sie zwar die Werte auf der rechten Seite wichtig finden, die Werte auf der linken Seite aber höher einschätzen. Der Wert ist eine Priorität für den Fall, dass beides konkurriert, keine Ablehnung von Dokumentation.

Was der Wert ablehnt, ist das dokumentationsgetriebene Projekt der 1990er-Jahre: Hunderte Seiten Spezifikation, abgenommen, bevor Code geschrieben wird, als Fortschritt an sich behandelt und aufgegeben, sobald der Code davon abweicht. Das entscheidende Wort ist umfassend: Dokumentation, die versucht, alles zu beschreiben, als Selbstzweck, und die höher geschätzt wird als das laufende System. Nichts im Manifest spricht gegen ein Kontextdiagramm, eine kurze Aufzeichnung, warum das Team asynchrones Messaging gewählt hat, oder ein Runbook, mit dem die Person in Rufbereitschaft um drei Uhr morgens den Dienst wiederherstellen kann.

Fachleute sind sich durchaus uneins, wie weit man gehen sollte. Manche agilen Coaches argumentieren, dass Gespräche und Tests fast immer ausreichen und dass schriftliche Architekturdokumentation schneller veraltet, als sie sich auszahlt. Andere, besonders wer langlebige Systeme wartet oder in regulierten Branchen arbeitet, weisen darauf hin, dass gerade die Menschen, die die Dokumentation am dringendsten brauchen (Nachfolger, Prüfer, das Betriebsteam), bei den Gesprächen fehlen. Beide Positionen sind sich über die zugrunde liegende Ökonomie einig: Dokumentation kostet etwas beim Schreiben, beim Aktuellhalten und beim Lesen, und sie lohnt sich nur dort, wo ihr Wert für die Leser diese Kosten übersteigt.

Gerade genug Dokumentation

Scott Amblers Formulierung „just barely good enough“ (gerade eben gut genug) beschreibt das Ziel: Ein Modell oder Dokument ist ausreichend, wenn es seinen Zweck für sein Publikum erfüllt, und Aufwand über diesen Punkt hinaus kostet mehr, als er einbringt. Sein Punkt, dass das Publikum und nicht der Autor entscheidet, ob ein Artefakt ausreicht, ist dasselbe Prinzip wie das Schreiben für den Leser. George Fairbanks führt das entsprechende Argument für die Architekturarbeit insgesamt in Just Enough Software Architecture (2010): Tun Sie so viel, wie die Risiken rechtfertigen (siehe Abschnitt 1.8).

Just-enough-Dokumentation ist daher keine feste Menge. Sie wächst mit der Größe und Lebensdauer des Systems, der Zahl der Teams, der Fluktuation, den Kosten eines Ausfalls und den Anforderungen der Aufsichtsbehörden. Ein Prototyp von zwei Personen braucht eine README und vielleicht ein Diagramm. Eine Zahlungsplattform, die von acht Teams unter Finanzregulierung betrieben wird, braucht Kontext-, Container- und Deployment-Sichten, ein Entscheidungsprotokoll, das Jahre zurückreicht, dokumentierte Sicherheitskonzepte und Nachweise, dass die Dokumente geprüft werden.

Ein praktisches Signal ist die wiederholte Frage. Wenn Neulinge in ihrer ersten Woche immer dasselbe fragen oder dieselbe Designdiskussion alle paar Monate wiederkehrt, gehört die Antwort aufgeschrieben. Ein anderes ist der teure Fehler: Hat ein Team eine ungeschriebene Regel gebrochen („Rufe den Zahlungsanbieter nie aus der Restaurant-App auf“), weil niemand sie ihm gesagt hat, dann war die Regel Architektur und hätte aufgeschrieben werden müssen.

Was sich zu dokumentieren lohnt und was nicht

Informationen unterscheiden sich auf zwei Arten, die bestimmen, wie man sie dokumentieren sollte. Die erste ist, ob sie sich aus dem Code ableiten lassen. Klassennamen, Methodensignaturen und Datenbanktabellen kann man jederzeit aus dem Quellcode lesen; die Gründe für eine Entscheidung, die Qualitätsziele des Systems und die verworfenen Optionen nicht, weil sie nie im Code standen. Die zweite ist, wie oft sie sich ändern. Der Zweck des Systems und seine wichtigsten externen Partner ändern sich selten; die Liste der Klassen in einem Modul ändert sich wöchentlich.

Handgeschriebene Architekturdokumentation sollte sich auf das konzentrieren, was wichtig ist und sich zugleich nicht aus dem Code ableiten lässt: Kontext und Abgrenzung des Systems (wer es nutzt und von welchen anderen Systemen es abhängt), seine Qualitätsziele und Randbedingungen, die wichtigsten Entscheidungen und ihre Gründe, die grobe Struktur (die wichtigsten deploybaren Teile und ihre Verantwortlichkeiten), das Deployment auf die Infrastruktur, die wichtigen Laufzeitszenarien und die querschnittlichen Konzepte, denen jeder Teil folgen muss, etwa wie Fehler behandelt, wie Benutzer authentifiziert und wie personenbezogene Daten geschützt werden. Diese Liste liegt nahe an der Struktur der arc42-Vorlage, die in Abschnitt 4.6 behandelt wird.

Nicht lohnenswert ist es, von Hand aufzuschreiben, was der Code oder die Werkzeuge bereits präzise aussagen und was sich oft ändert: Klassendiagramme einer ganzen Codebasis, Listen von Endpoints, die eine OpenAPI-Datei bereits enthält, oder Beschreibungen jeder einzelnen Funktion. Wo solche Sichten nützlich sind, generieren Sie sie in der Build-Pipeline aus dem Quellcode, damit sie nicht abdriften können. Lassen Sie außerdem Wunschdenken weg (Diagramme davon, wie das System aussehen sollte, präsentiert, als sähe es schon so aus), Protokolle von Meetings, deren Ergebnis anderswo festgehalten ist, und doppelten Text, der irgendwann seiner Kopie widersprechen wird.

Sieben Regeln für gute Dokumentation

Views and Beyond stellt sieben Regeln für gute Dokumentation auf. Es lohnt sich, sie auswendig zu kennen, denn fast jedes Scheitern von Dokumentation verstößt gegen eine davon.

Lebende Dokumentation und Docs as Code

Das klassische Scheitern von Architekturdokumentation ist das Veralten: Die Beschreibung wird zu Beginn geschrieben, das System ändert sich, und niemand aktualisiert das Dokument, weil es getrennt von der Arbeit liegt. Zwei verwandte Ideen packen dieses Problem an der Wurzel.

Docs as Code, eine von der Write-the-Docs-Community geförderte Praxis, bedeutet, Dokumentation wie Quellcode zu behandeln: in Klartextformaten wie Markdown oder AsciiDoc geschrieben, in der Versionskontrolle gehalten (meist im selben Repository wie der beschriebene Code), über dieselben Pull Requests geändert, von denselben Menschen geprüft und von derselben Pipeline gebaut und veröffentlicht. Von einem Pull Request, der ändert, wie Bestellungen disponiert werden, kann man dann verlangen, dass er im selben Commit die Laufzeitsicht aktualisiert, und der Reviewer sieht beides.

Lebende Dokumentation, ein Begriff, den Cyrille Martraires gleichnamiges Buch (2019) bekannt gemacht hat, geht weiter: Wo immer möglich, sollte Dokumentation aus dem System selbst abgeleitet werden, damit sie nicht abdriften kann. Aus dem Code generierte Abhängigkeitsdiagramme, aus OpenAPI-Dateien generierte API-Referenzen, durch automatisierte Tests geprüfte Architekturregeln und Diagramme, die aus einem neben dem Code gehaltenen Modell generiert werden, sind Beispiele dafür. Handgeschriebener Text bleibt dem vorbehalten, was sich nicht ableiten lässt, vor allem Absicht und Begründung.

Keine der beiden Ideen erspart das Urteil darüber, was man aufschreiben sollte. Abschnitt 4.7, Diagrams as Code, behandelt die Werkzeuge und Gewohnheiten im Detail.