Zu wenig Architekturdokumentation begegnet uns dauernd, einfach weil es häufig niemand gerne macht und es auch in der Priorität bevorzugt hinten runterfällt.

Eine sehr umfangreiche Architekturdokumentation ist hingegen eher selten. Gibt es aber auch in verschiedenen Ausprägungen. In diesem Artikel schreibe ich über ein Anti-Pattern, das nicht allzu häufig auftritt, das aber auch höchst problematisch ist und unbedingt erkannt und abgestellt werden muss.

Anti-Pattern: Unmengen an allgemeiner Dokumentation über Architektur, zusammengetragen aus Büchern & Co

Vielleicht kennt ihr das: Auf den ersten Blick ist man freudig überrascht, dass es überhaupt Architekturdokumentation zu einem Softwaresystem gibt. Und dann gleich auch noch recht viel davon. Das Ganze auch noch halbwegs gut strukturiert. Im Inhaltsverzeichnis finden sich gängige Konzepte und alles sieht überwiegend zeitgemäß aus. Bis hierhin: Vorfreude auf den Inhalt.

Bei genauer Betrachtung weicht dann aber die Freude immer mehr der Ernüchterung: Da steht zwar viel über Softwarearchitektur, aber nichts Konkretes. Vor allem kaum etwas, das mit dem aktuellen System zu tun hat. Und das manchmal auf Hunderten oder im Extremfall sogar Tausenden Seiten.

Konzepte sind nur allgemein genannt und beschrieben, aber nicht ausgeprägt. „Wir haben eine service-orientierte Architektur mit Microservices“ oder „Wir setzen vollständig auf Event-Orientierung“. Damit die Dokumentation trotzdem richtig schön ausführlich wird, sind dann die allgemeinen Konzepte wie Service-Orientierung, Event-Orientierung oder Containerisierung ausführlichst beschrieben. Teilweise 1:1 aus Büchern oder sonstigen Quellen übernommen. Manchmal werden sogar noch ausführliche Abwägungshilfen dargelegt, wie denn z.B. zwischen Umsetzungsvarianten der Service-Orientierung zu entscheiden sei (teils auch aus den Quellen übernommen).

Wie erkenne ich, dass das Anti-Pattern bei uns zugeschlagen hat?

Wie wir gleich noch sehen werden, ist das Anti-Pattern sehr schädlich und muss unbedingt frühzeitig erkannt werden. Zentrales Indiz: häufig fehlen dann die eigentlichen Architekturentscheidungen und ihre ganz konkrete Ausgestaltung:

• Welche Entscheidungen wurden konkret getroffen? Stattdessen stehen unaufgelöste Entscheidungen da und Entscheidungshilfen.
• Wie ist die Entscheidung durch konkrete Anforderungen getrieben? Stattdessen gibt es keine konkreten Anforderungen, sondern nur allgemeine Anforderungen, die für alle möglichen Systeme gelten könnten.
• Welche konkrete Ausgestaltung für Architekturkonzepte wurde gewählt und wie wird die konkrete Fachlichkeit damit umgesetzt? Stattdessen bleibt es bei einer rein technischen Betrachtung, die losgelöst ist vom konkreten Fall.
• Wie integrieren sich einzelne Konzepte untereinander und wie spielen sie zusammen zur Erreichung von Anforderungen? Stattdessen stehen alle Konzepte isoliert nebeneinander und es fehlt jegliche Information, wie sie denn umgesetzt werden sollen.

Während also ganz viel fehlt, ist gleichzeitig eine Menge an Dokumentation vorhanden, die völlig unnötig ist. Es bringt einfach keinen Wert, die allgemeinen Informationen aus Büchern oder aus sonstigen Quellen noch mal abzuschreiben: Es ist viel besser, sie am ursprünglichen Ort zu belassen und zu referenzieren. Erfahrene Architekten und Entwickler kennen diese Informationen häufig auch schon und wollen sich im Rahmen der Architekturdokumentation beim Lesen auf das fokussieren, was wirklich spezifisch ist für das System.

Ich habe schon Extremfälle von Dokumentationen gesehen, bei denen fast nichts übriggeblieben ist, sobald alle allgemeinen und kopierten Informationen eliminiert waren.

Was sind die Konsequenzen des Anti-Patterns?

Eine solche Architekturdokumentation ist die ideale Grundlage für Täuschungsmanöver unterschiedlicher Art und damit für Betrug, Selbstbetrug und langfristigen Misserfolg:

• Zunächst ist für alle Beteiligten der Blick verschleiert: Es steht ja schon viel da und in den vielen Seiten wird sich ja schon was Passendes verbergen. Vielleicht sieht man es nur nicht direkt. Wer nur drüber scrollt, weil er mal sehen möchte, ob schon was da ist, der wird von bekannten Konzeptnamen und Buzzwords freundlich begrüßt und fühlt sich in bekanntem Terrain aufgehoben und hat den Eindruck, dass „State-of-the-Art“ gearbeitet wird.
• Die Grundlage für eine saubere Kommunikation fehlt: Alles, was aufgeschrieben ist, ist nicht falsch und deshalb kann man dem auch nicht widersprechen. Es fehlt nur alles, was eigentlich wichtig wäre. Da traut sich aber oft länger niemand, das tatsächlich auszusprechen, weil niemand kritisiert werden soll.
• Es gibt nicht nur keine gute Dokumentation, die Konsequenz ist, dass es auch keine passenden Konzepte und damit keine passende Architektur gibt. Damit fehlt die absolute Grundlage, um überhaupt etwas Sinnvolles zu entwickeln. Leider führt aber auch das öfter mal nicht dazu, dass jetzt alle anfangen zu protestieren und eine bessere Konzeption einfordern. Stattdessen nutzen manche die vermeintlichen Freiheiten und designen on-the-fly ihre Konzepte mit dem gegebenen riesigen Interpretationsspielraum. Die sind dann nirgends dokumentiert, nicht konsistent umgesetzt und meistens nicht sonderlich durchdacht und geeignet.
• Eine solche abgeschriebene Dokumentation kostet trotzdem große Mengen an Zeit und Geld: Bis hunderte oder gar tausende Seiten kopiert, abgeschrieben oder zusammengefasst sind, können Monate an Zeit ins Land gehen und Hunderttausende Euros verbraten werden.

Deshalb ist eine Architekturdokumentation, die dieses Anti-Pattern „umsetzt“, sogar bedeutend schädlicher, als keine Dokumentation. Keine Dokumentation kostet wenigstens nichts und man sieht direkt, dass nichts von Wert da ist.

In welchen Situationen tritt das Anti-Pattern gerne auf?

Es gibt einige Kontextfaktoren, die in meiner Erfahrung dieses Anti-Pattern begünstigen:

• Die Anforderungen sind noch sehr rudimentär erarbeitet und vor allem Qualitätsanforderungen noch kaum skizziert und verfeinert. Trotzdem ist natürlich die Zeit knapp und jemand soll schon mal loslegen und die Architektur konzipieren und dokumentieren: Mangels passenden Inputs bleibt die Architektur dann oft extrem vage.
• Der Managementstil ist sehr Prozess- und KPI-fokussiert: wenn hart eingefordert wird, dass bis zu einer bestimmten Deadline ein bestimmtes Artefakt da sein muss und dann vor allem syntaktische Eigenschaften wie Umfang etc. geprüft werden, dann ist es verlockend, die abgeprüften Ziele zu erfüllen und damit aber am eigentlichen Ziel vorbeizuschießen.
• Es sind Personen mit der Aufgabe betraut, die Architektur zu konzipieren und zu dokumentieren, denen die Erfahrung fehlt. Dann ist es ganz natürlich, sich an vorhandenem Material wie Büchern, Konferenzvorträgen etc. entlangzuhangeln und somit zumindest irgendein Ergebnis vorweisen zu können.
• Externe Mitarbeiter und Berater, die entweder nach geleisteter Zeit oder nach Ergebnisumfängen bezahlt werden, können manchmal auch dazu neigen, in dieses Anti-Pattern zu verfallen. Vor allem, wenn auch noch ein oder mehrere der voranstehenden Punkte eintreffen.

• In Projekten der öffentlichen Hand und auch in öffentlich geförderten Forschungsprojekten tritt das Anti-Pattern auch gehäuft auf: Oft kombinieren sich etliche der voranstehenden Punkte, das Budget scheint erst mal großzügig bemessen und es arbeiten Beteiligte mit teilweise sehr unterschiedlichen Interessenslagen mit.

Wie vermeide ich, dass das Anti-Pattern auftritt?

Der absolut zentrale Punkt ist, darauf zu achten, dass wirklich eine solide Konzeption der Architektur des Systems gemacht wird (siehe Artikel ”Das macht man heute so!” – Ein mieser Grund für Architekturentscheidungen!) und diese dann auch aufgeschrieben wird (siehe Artikel System schlägt Template: Wider Schema F bei Architektur-Dokumentationen). Dazu müssen die richtigen Voraussetzungen und Rahmenbedingungen geschaffen werden, vor allem auch im Hinblick auf zugrundeliegende Anforderungen, die herausgearbeitet sein müssen.

Wer selbst die Architektur gestaltet und dokumentiert, hat es natürlich erst mal selbst in der Hand. Aber auch dann kann es vorkommen, dass man stark für eine sinnvolle Vorgehensweise kämpfen muss, wenn viel Druck ausgeübt wird „Fortschritt“ und „Ergebnisse“ zu produzieren. Dann nicht der Versuchung erliegen, einfach mal allgemeines Wissen abzuschreiben, um nicht negativ aufzufallen.

Wer für ein gesamtes Produkt oder Team verantwortlich ist, muss eine Kultur schaffen, die keine Anreize in die falsche Richtung setzt und keinen leeren Inhalt als Ergebnis belohnt. Zusätzlich braucht es regelmäßige Architektur-Reviews (siehe Artikel Ich will sehen., Architekturbewertung – Essenz und Risiken eines Software-Systems freilegen), in denen der Fokus darauf liegt, unter Kollegen einen ehrlichen Blick auf die Konzepte und den Fortschritt zu richten. Zusätzlich werden die Konzepte damit im Team verbreitet und die gemeinsame Akzeptanz steigt. Außerdem braucht es dafür eine Kultur, Dinge offen diskutieren und kritisieren zu können.

Wie immer, müssen Personen für die Aufgabe der Konzeption und Dokumentation gefunden werden, die diese Aufgaben auch machen wollen und können (siehe Artikel Gute Doku, dankbares Team: Phantom­bildzeichner für Softwarearchitektur!)

Fazit

„Viel hilft viel“ gilt bei der Architekturdokumentation auf keinen Fall. Architektur muss spezifisch für das jeweilige System erarbeitet und auch dokumentiert werden.

Bücher über Architektur vs. Deine Architekturdokumentation

In Büchern über Architekturen und Architekturmuster geht es darum, für viele Systeme passende allgemeine Vorlagen und Entscheidungshilfen zu liefern. Deshalb müssen sie immer von konkreten Situationen und auch der Fachlichkeit abstrahieren und trotzdem hilfreiche Entscheidungsunterstützung liefern. So beschreiben sie verallgemeinerte Situationen und Herausforderungen und skizzieren allgemeine, technische Lösungen, häufig auch mit eher isolierten Konzepten.

In Deiner Architekturdokumentation geht es darum, ganz konkret zu beschreiben, wie die Architektur in deinem System konzipiert wurde und warum sie so konzipiert wurde und warum andere konkrete Alternativen verworfen wurden. Dies braucht viel Konkretheit, Abbildung der Fachlichkeit auf die Technik und saubere Verzahnung aller beteiligten Konzepte und Entscheidungen.

Natürlich lohnt es sich enorm, viele Bücher über Architekturmuster zu lesen und damit viele mögliche Alternativen zu kennen. Dann muss dieses Wissen aber transformiert und angewendet werden, sodass die konkrete eigene Architektur entsteht.

Das gilt genauso auch für viele andere Themen in der Softwareentwicklung, wie z.B. beim UX-Design für ein System oder auch beim Aufsetzen des Entwicklungsprozesses für ein Projekt.