Leute, wir brauchen bessere Architekturdokumentationen! Jetzt. Denn in quasi allen Projekten, in denen wir unterwegs sind, ist die Architekturdokumentation ungenügend. Und das in jeglicher Hinsicht: Es wird viel zu wenig aufgeschrieben, insbesondere die zentralen Entscheidungen und kritischen Punkte sind nicht dokumentiert, Architekturtreiber werden nicht präzise erfasst, Informationen sind veraltet, die Struktur ist degeneriert, etc.  … Desaströse Zustände.

Architekturdokumentation: integraler Bestandteil der Entwicklungsarbeit

Das ist schlecht, denn eine gut geeignete Architektur zu gestalten und diese auch in geeigneter Weise aufzuschreiben, sind integrale Bestandteile von Softwareentwicklung. Ohne geht es nicht:

1. Architekturdokumentation dient als persistenter Informationsspeicher. Kein Mensch ist in der Lage, in der Flut von Details alle Aspekte gleichzeitig im Kopf zu behalten, weder beim Architekturdesign noch während der Implementierung. Schon gar nicht funktioniert das über Wochen und Monate. Jede:r weiß von sich selbst, wie schnell wir Dinge vergessen. Zu glauben, wir könnten so komplexe Strukturen wie Softwaresysteme konstruieren und bauen und uns gleichzeitig über lange Zeit alles merken, ist naiv.

2. Aufschreiben hilft uns, Dinge zu vervollständigen und sie zu präzisieren. Wer kennt das nicht: Eigentlich erscheint ein Konzept schlüssig, bis man es aufschreiben muss. Dann fallen einem alle möglichen Aspekte ein, die noch offen sind oder die vielleicht so doch nicht zusammenpassen. Durch Dokumentation kommen wir notwendigerweise zu einer durchdachteren und damit auch besseren Umsetzung.

3. Architekturdokumentation ist ein unverzichtbares Kommunikationsmedium. Ja, direkte Kommunikation ist zum initialen Austausch von Ideen sehr effektiv, aber ohne die Möglichkeit etwas nachzulesen, würden wir zu nichts anderem mehr kommen als die ganze Zeit miteinander zu sprechen: „Kannst du mir nochmal kurz sagen, wie das gedacht war?“, „Wie wollten wir das nochmal nennen?“, „Warum hatten wir das nochmal so entschieden?“ Den meisten kommt bei mehr als zwei unangekündigten Unterbrechungen schon das kalte Grausen. Das geht so nicht. Außerdem arbeiten wir viel in verteilten Situationen, sodass asynchrone Kommunikation immer wichtiger wird.

Architekturdokumentation wird dennoch vernachlässigt

Warum wird Architekturdokumentation dennoch so häufig vernachlässigt? Einerseits werden alle Ergebnisse und Artefakte, die nicht der lauffähige Code sind, unter Zeitdruck gerne fallengelassen („Keine Zeit, die Axt zu schärfen, wir müssen Bäume fällen!“). Nachhaltig gedacht ist das aber nicht, denn Architektur und deren Dokumentation sind Zeitinvestitionen, die man macht, damit die Umsetzung einfacher, schneller und besser gelingt. Aus dem gleichen Grund sollte man auch nicht aufs Testen verzichten: Ja, kurzfristig hat man ein wenig Zeit gespart, aber die Zinsen dafür zahlt man ziemlich schnell. Und die sind knackig.

Ja, Architekturdokumentation ist ein Zwischenprodukt und im Endeffekt kommt es auf den Code an, der läuft und damit auch Geschäftswert generiert. Aber da, wo die Zwischenprodukte schlecht sind, wird auch das Endprodukt selten besser. Vielleicht bekommen manche so trotzdem ein lauffähiges System hin. Aber das kann doch nicht unser Qualitätsanspruch sein. Wir haben nicht den Auftrag, irgendwie lauffähige Systeme zu bauen – wir haben den Auftrag, richtig gute, performante, sichere und langlebige Systeme zu bauen. Das diktiert allein das Arbeitsethos. Und deswegen sollten wir auch mit dem gleichen Anspruch an der Architekturdokumentation arbeiten, wie am eigentlichen System. Und das macht uns im Endeffekt auch nicht langsamer, sondern schneller: „Slow is smooth, smooth is fast.“

Andererseits macht es vielen Entwickler:innen einfach nicht so viel Spaß, Dokumentation zu schreiben. Häufig wird dann argumentiert „Ich kann das leider nicht so gut, es wäre gut, wenn das jemand anders aufschreiben könnte.“

Spaß an der Aufgabe ist aber nicht maßgeblich. Ja, wir wollen nicht die ganze Zeit an Dingen arbeiten, die wir ätzend finden. Aber andererseits sind wir ja auch nicht auf einer Karibik-Kreuzfahrt. Als Softwareingenieure gehört es zu unseren Aufgaben, Pläne zu konstruieren und diese aufzuschreiben, und das in gut. Ein:e Maschinenbauer:in oder Architekt:in verzichtet auch nicht darauf, Pläne aufzuschreiben, weil es unter ihren Aufgaben diejenige ist, die ihr am wenigsten zusagt. Es muss halt gemacht werden. Und Dinge, die man nicht gut kann, kann man üben, um darin besser zu werden.

Aus einer gut gemachten Architekturdokumentation lässt sich ebenso berufliche Befriedigung ziehen, wie aus gut geschriebenem Code. Insbesondere, wenn man sich anschaut, welchen Impact man damit hat, auf alle Stakeholder im Projekt. Aussagen wie „Endlich ist hier mal was richtig aufgeschrieben“, „Jetzt kann man direkt mal verstehen, wie das funktioniert“ oder „Das hat mir das Leben so viel einfacher gemacht“ zeigen deutlich, wie sehr sich die Investition lohnt.

Eigenschaften guter Architekturdokumentation

Ich hoffe, bis hierher sind wir uns einig geworden, dass es sinnvoll ist, die Architektur des Systems zu dokumentieren und auch zu versuchen, das in möglichst guter Weise zu tun. Aber was macht eine „gute“ Architekturdokumentation aus? Mit der folgenden Liste wollen wir einige Eigenschaften von guten Architekturdokumentationen aufzeigen und erläutern. Damit bekommt man leider keine genaue Anleitung, wie diese Eigenschaften zu erreichen sind, aber doch eine Liste von Dingen, auf die man achten kann und wonach man streben sollte.

• Präzision: Präzision bedeutet genaues Arbeiten und Beschreiben. Wir müssen Gleichheit und Unterschiede erkennen, Fälle auseinanderziehen, Details beachten und Sonderfälle beschreiben.

• Vollständigkeit: Vollständigkeit bedeutet nicht, alles, was man sagen könnte, auch aufzuschreiben oder den Code nachzuerzählen. Wichtig ist jedoch, alle zentralen Punkte, die zum Verständnis der Struktur und Funktionsweise des Systems in seiner Gesamtheit sowie jedes einzelnen Konzepts notwendig sind, verständlich zu erläutern.

• Kompaktheit: Kompaktheit auf der anderen Seite bedeutet, keine Informationen in der Architekturdokumentation zu belassen, die nicht unbedingt notwendig sind. Die erzeugen unnötiges Rauschen und mindern so den Wert der Dokumentation massiv. Insbesondere sollten wir nicht Seiten mit Informationen zu Konzepten füllen, die man auch in der Literatur nachlesen kann, wie beispielsweise Grundlagen zu REST oder Event-driven Architecture (ja, das haben wir schon gesehen).

• Konkretheit und gute Beispiele: Keine Dokumentation ohne gute Beispiele. Beispiele tragen ungemein zum Verständnis bei. „Komponente A“, „Komponente B“, „Komponente C“ sind keine guten Beispiele. Gute Beispiele sind konkret und repräsentativ.

• Verständlichkeit: Eine gute Architekturdokumentation muss verständlich sein. Das heißt nicht, dass eine Marketingmitarbeiter:in die Dokumentation verstehen muss. Andererseits sollte es aber auch nicht so sein, dass die Dokumentation nur für Personen geschrieben wird, die das System bereits seit Jahren betreuen. Eine gute Heuristik ist, dass die Dokumentation für eine Person mit erwartbarem Basiswissen zugänglich sein sollte, also für jemanden mit einem technischen Hintergrund, der oder die schon Systeme entwickelt hat und grundsätzlich das Projekt kennt.

• Konsistenz und Einheitlichkeit: Konsistenz und Einheitlichkeit bedeuten, dass gleiche Dinge immer wieder in der gleichen Art und Weise dargestellt werden: Gleicher Aufbau, Wiederverwendung von Darstellungen oder konsistente Notationen sind Beispiele. Das trägt ungemein zu Einfachheit und Verständlichkeit der Architekturdokumentation bei.

• Strukturiertheit: Strukturiertheit bedeutet einerseits, dass der Aufbau der Architekturdokumentation einer klaren und leicht verständlichen Struktur folgt, sodass gesuchte Inhalte möglichst schnell gefunden werden können. Andererseits bezieht sich Strukturiertheit auch auf die einzelnen Artikel oder Abschnitte: Diese sollen klar und verständlich aufgebaut sein, und wichtige Details sollen deutlich herausgearbeitet werden.

Arbeit an Architekturdokumentation

Architekturdokumentation ist also wichtig und wir wollen nicht nur irgendeine, sondern eine gute Architekturdokumentation haben. Wie arbeiten wir nun also an der Architekturdokumentation, dass wir das hinbekommen? Hier sind einige Gedanken dazu:

• Plant nicht damit, eine vollständige Architekturdokumentation gleich zu Anfang des Projekts vor der Umsetzung zu schreiben. Das wird nicht gelingen und ist auch nicht das Ziel. Es ist sinnvoll, einen initialen Entwurf der Architektur des Systems zu erarbeiten und diesen auch zu dokumentieren. Ab dann sollte die Architekturdokumentation ein lebendes Artefakt im Entwicklungsprozess sein, das sich stetig weiterentwickelt.

• Architekturdokumentation hat eine Tendenz dazu, ständig zu erodieren. Erosion heißt hier, es entsteht eine Lücke zwischen der Dokumentation und der tatsächlichen Implementierung. Lässt man es zu, dass diese Lücke wächst, schrumpft der Mehrwert der Dokumentation kontinuierlich. Erosion kann nur durch kontinuierliche Investition und Arbeit an der Architekturdokumentation bekämpft werden. Und das sollte man auch einplanen und tun.

• Die Idee, dass sich eine Person hauptsächlich um die Architekturdokumentation kümmert, während die anderen im Team die Umsetzung machen, ist zum Scheitern verurteilt. Es ist einfach nicht möglich, den kontinuierlichen Änderungen aller Entwickler:innen hinterherzuschreiben. Stattdessen braucht es eine andere Kultur: Dokumentation ist die Aufgabe des gesamten Teams. Natürlich kann es Dokumentationsverantwortliche geben, die die Gesamtqualität der Architekturdokumentation im Blick behalten, aber grundsätzlich ist jeder dafür verantwortlich, Inhalte zur Architekturdokumentation beizutragen.

• Dokumentation gehört in die Definition of Done. Das gilt ohnehin für Konzeptionsaufgaben; aber auch bei Umsetzungsaufgaben sollte es klar sein, dass es dazugehört, die Architekturdokumentation entsprechend den durchgeführten Änderungen zu aktualisieren.

• Zur Review gehört auch eine Review der Dokumentation. Mehr Augenpaare sehen mehr. Damit wird die Dokumentation besser und Wissen verbreitet sich schneller im Team.

• Eine schlechte Architekturdokumentation aufzuräumen, ist sehr viel schneller und günstiger zu machen, als eine schlechte Architektur zu reparieren. Der dafür notwendige Aufwand lohnt sich fast immer.

Feldnotizen Architekturdokumentation – pragmatische Tipps für bessere Architekturdokumentationen

In unseren Aufträgen spielt Architekturdokumentation häufig eine Rolle; oft dokumentieren wir die Architektur schon existierender Systeme nach, als Grundlage für daran anschließende Verbesserungsaktivitäten. So haben wir mittlerweile an einigen Dutzend Architekturdokumentationen von Unternehmen unterschiedlichster Branchen gearbeitet.

Mit diesem Artikel setzen wir den Startpunkt für eine Artikelreihe „Feldnotizen Architekturdokumentation“, bei der wir, basierend auf unseren Erfahrungen mit Architekturdokumentationen in der Praxis, pragmatische Tipps geben, wie man zu besseren Architekturdokumentationen kommt. Wir berücksichtigen dabei die übergreifende Struktur bis hin zu den Details von Diagrammgestaltung. Denn oft braucht es keine großen Änderungen oder tiefgreifende Umbauarbeiten, um eine substanzielle Verbesserung herbeizuführen.

So sehen wir hoffentlich künftig mehr Architekturdokumentationen, die ihrer Bedeutung für die Softwareentwicklung und unser aller Qualitätsanspruch als Softwareingenieure gerecht werden.