Leute, wir brauchen bessere Architekturdokumentationen! Jetzt.

In quasi allen Projekten, in denen wir unterwegs sind, ist die Architekturdokumentation ungenügend. Und das in jeglicher Richtung: 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 ist ein integraler Bestandteil der Entwicklungsarbeit

Das ist schlecht, denn eine gut geeignete Architektur zu gestalten und diese dann auch in geeigneter Weise aufzuschreiben, sind integrale Bestandteile von Softwareentwicklung. Architekturdokumentation dient als persistenter Informationsspeicher, sie hilft, Dinge zu vervollständigen und sie zu präzisieren und sie dient als unverzichtbares Kommunikationsmedium.

Kurzum: Ohne Architekturdokumentation geht es nicht!

Architekturdokumentation wird häufig 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 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.

Andererseits macht es vielen Entwickler:innen einfach nicht so viel Spaß, Dokumentation zu schreiben. Aber als Software-Ingenieure gehört es zu unseren Aufgaben, Pläne zu konstruieren und diese auch aufzuschreiben, und das in gut 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 sehr 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 zeigen und erläutern:

• 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.
• Kompaktheit: Kompaktheit auf der anderen Seite bedeutet, keine Informationen in der Architekturdokumentation zu belassen, die nicht unbedingt notwendig sind. Dies erzeugt unnötiges Rauschen und mindert so den Wert der Dokumentation massiv. Insbesondere sollten wir nicht Seiten füllen mit Informationen zu Konzepten, die man auch in der Literatur nachlesen kann, wie beispielsweise Grundlagen zu REST oder Event-Driven Architecture (Ja, das haben wir schon gesehen).
• Konkretheit & 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.
• Konsistenz & Einheitlichkeit: Konsistenz und Einheitlichkeit bedeutet, dass gleiche Dinge immer wieder in der gleichen Art und Weise dargestellt werden: Gleicher Aufbau, Wiederverwendung von Darstellungen oder konsistente Notationen sind Beispiele. Dies trägt ungemein zu Einfachheit und Verständlichkeit der Architekturdokumentation bei.

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, so dass wir das hinbekommen? Hier sind einige Gedanken dazu:

• Plant nicht damit, eine vollständige Architekturdokumentation gleich zu Anfang des Projektes 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 den dann auch zu dokumentieren. Ab da sollte die Architekturdokumentation ein lebendes Artefakt im Entwicklungsprozess sein, das sich stetig weiterentwickelt.
• Architekturdokumentation hat eine ständige Tendenz dazu, zu erodieren. Erosion heißt, 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 tun.
• 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.
• 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.

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 arbeiten.

Auf unserem Blog schreiben wir immer wieder über Tipps aus der Praxis für bessere Architekturdokumentationen. Im Java-Magazin erscheint außerdem die Artikelserie „Feldnotizen Architekturdokumentation“, in der wir unsere Tipps aufbereiten und monatlich neue Tipps als Artikel veröffentlichen.

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