Softwarearchitekturen dokumentieren und kommunizieren

Softwarearchitekturen dokumentieren und kommunizieren

Mein Fazit: Ziel des Buches ist es, den Leser viele wichtige Informationen und praktischen Beispiele in die Hand zu geben, um die Architektur jedes Software-Produktes angemessen zu beschreiben. arc42 zieht sich als roter Faden durch das Buch. Eine gute Wahl, wie ich finde. Ich musste aber schnell feststellen, dass der Autor wenig auf agile Methoden eingeht. Das ist eigentlich schade. Ich hatte die Hoffnung, dass der Autor den Kreis bei der Dokumentation größer zieht. Den gerade agile Methoden brauchen keine scharfe Trennung in fachliche Anforderungen und technische Dokumentation. Bei den Praxisbeispielen fehlen mir moderne Architekturen.


Kapitel Eins geht auf Motivation und Zielsetzung des Buches ein. Der Titel des Buches ist eigentlich eindeutig: Ein Fachbuch für Architekturdokumentation. Spätestens am Ende dieses Kapitels lässt der Autor keine zweifel über die Zielsetzung.

« Zielgruppe des Buches sind Softwareentwickler und -architekten, die die Entwurfsideen ihrer Vorhaben wirkungsvoll festhalten und dabei nicht im Dokumentationsstrudel untergehen wollen. »

Das klingt für mich nach Phasendenken. Es fehlt mir der Ausblick auf die Chancen durch Agilität in der Software-Entwicklung.

In Kapitel Zwei versucht sich der Autor an einer Definition von Software-Architektur für sich und das Buch. Er legt sich schnell fest, Architektur als Summe wichtiger Entscheidungen zu verstehen. Bei der Frage, wie eine Software-Architektur entsteht, bietet er dem Leser die Architekturbrezel an. Auch das ist Phasendenken. Wieder fehlt mir die Betrachtung agiler Methoden. Der Autor möchte nicht zwischen Architekt und Entwickler unterscheiden.

Ein guter Praxistipp ist die Einführung der Rolle “Doctator”. Ich finde den Begriff nicht gelungen, er klingt wie Diktator. Nicht sehr positiv. Aber die Rollenbeschreibung erinnert mich sehr stark an den Gärtner der Methode CARDS+.

Eine weitere gute Idee ist der Produktkarton. Sein Zweck ist die Darstellung der wesentlichen Ziele und Merkmale des System auf einem Blatt Papier.

Für die Abgrenzung des Systemkontextes schlägt der Autor ganz klassisch UML vor. Mit seinen beiden Praxisbeispielen illustriert er die Schwierigkeiten, die es hier geben kann. Mehr Technisch, oder doch fachlich. Wann ist eine Komponente doch ein Fremdsystem. Das ist nicht besonders aufregend. Viel spannender sind seine Verwendung von Randbedingungen und Qualitätsmerkmalen. Aber auch hier verliert er sich wie beim Systemkontext in Details, die meiner Ansicht nicht notwendig sind. Auch der Aufwand für die Erstellung von Qualitätsszenarien erscheint wir für agile Software-Projekte einfach zu hoch zu sein.

Ganz zum Schluss, auf einer halben Buchseite, gibt der Autor den guten Rat, doch von Anfang an ein Glossar zu führen. Allerdings schlägt er ein ausgedünntes Glossar für den Architekturüberblick vor. Warum das denn?

Entscheidungen sind das Thema in Kapitel Drei. Aufgrund der Definition von Software-Architektur in Kapitel Zwei haben Entscheidungen natürlich einen sehr hohen Stellenwert. Viele Praxisbeispiele sind für meinen Geschmack zu kleinteilig (Zitat: Sind Stellungsobjekte veränderlich) oder zu allgemein (Zitat: Wie adressieren wir querschnittliche Themen). Der Kernaussage dieses Kapitels ist nichts hinzuzufügen: Der Lösungsweg ist mindestens so interessant wie die getroffene Entscheidung, ebenso die Begründung.

Entscheidungen unterliegen verschiedenen Einflussfaktoren. Hier verwendet der Autor die in Kapitel Zwei eingeführten Randbedingungen und Qualitätsziele, um mit Mindmaps oder Kreuztabellen Übersicht zu schaffen. Mit einer Lösungsstrategie bietet der Autor eine besonders kompakte Form zur Dokumentation und Kommunikation der Architektur an. Insgesamt erscheint mir der Aufwand sehr hoch für die Erstellung und vor allem Pflege dieser Dokumentationsmittel.

« Die Lösungsstrategie in der gezeigten Form ist nicht nur exzellent geeignet, um die grundlegensten Aspekte Ihrer Architektur zu nennen und dabei gleichzeitig zu motivieren. Sie hilft auch während des Entwurfs der Architektur dabei, Lücken und Ungereimtheiten aufzudecken. »

Es drängt sich auf, dass der Autor den Entwurf der Architektur erneut als Phase betrachtet. Dadurch bleibt für mich offen, wie die Arbeitsweise bei agiler Entwicklung aussieht.

Kapitel Vier hält ein Plädoyer für eine feste Gliederung bei einer Architekturdokumentation. arc42 in Aktion. In Ordnung.

Sichten sind das Thema in Kapitel Fünf. Der Autor beginnt mit der Bausteinsicht. Die zentrale Tätigkeit beim Architekturentwurf besteht aus der Zerlegung des Systems in Bausteine. Mit jeder Bausteinebene werden mehr Einzelheiten sichtbar. Und ein guter Rat des Autors folgt: Detaillieren nach Augenmaß. Das Praxisbeispiel “DokChess” ist eher untauglich, da es zu code-nah ist. Das Praxisbeispiel “immer-nur-schach.de” ist schön modelliert mit den Schichten Applikation, Geschäftslogik, Persistenz und Integration. Aber eine moderne Architektur sieht anders aus, finde ich.

Eine Schnittstellenbeschreibung bietet eine vereinfachte Sicht auf einen Baustein. Das ist gut. Was mir fehlt, ist die Abgrenzung. Mir wird einfach nicht klar, wann ich eine Schnittstellenbeschreibung erstellen soll. Bei lokalen Funktionsaufrufen? Doch eher nicht. Beim Austausch von Nachrichten? Gute Idee.

Mit Laufzeitsichten stehe ich persönlich auf Kriegsfuß. Sie sind entweder zu abstrakt oder zu genau. Im zweiten Fall ist die Wahrscheinlichkeit sehr groß, dass die Dokumentation aufgrund von Refactorings nicht mehr zum Code passt. In beiden Fällen muss ich den Code lesen, um die Wahrheit herauszufinden. Dann lass ich die Laufzeitsicht lieber gleich weg und schreibe lesbaren Code. Wäre es nicht ausreichend, einfache Abfolgen von Bausteinen unter dem Blickwinkel einer fachlichen Funktion aufzuschreiben, um das Verhalten eines Systems zu zeigen?

Im Zeitalter von Verzeichnisdiensten und Virtualisierung in der Cloud stelle ich die Verteilungssicht ganz stark in Frage. Die Verteilung ergibt sich bei vollautomatisierten Systemen aus Skripten und Konfigurationsdateien. Wozu soll ich eine Umgebung dokumentieren? Es ist doch viel zielführender, die Artefakte des Deployments für Menschen lesbar zu machen. Beispiele dafür sind Gitlabs Auto DevOps oder Rancher.

Kapitel Fünf endet mit der Empfehlung, Muster zu kommunizieren, und geht so  fließend in Kapitel Sechs über: Übergreifende Konzepte. Im Wesentlichen will der Autor erklären, wie man umfassende Konzepte gliedert.

In Kapitel Sieben dreht sich alles um Werkzeuge. Visuell oder verbal ist eine Frage, die der Autor am Ende so beantwortet:

« In der Praxis greifen Sie und Ihr Team bei Dokumentationsmitteln oft auf Mischformen zurück. Ein als Text verfasstes Konzept wird um Abbildungen angereichert, kaum eine Grafik in einer Architekturdokumentation kommt ohne Beschriftungen und zusätzliche Beschreibungen aus. »

Nach der “Toolparade” kommt die nächste spannende Frage: Kathedrale oder Bazar? Er bezeichnet die Verwendung eines Wiki (Bazar) und eines UML-Tools (Kathedrale) als Extrempunkte im Spektrum der Werkzeuge. Ich finde, hier macht es sich der Autor sehr einfach. Die Beschreibung vor allem der Schwächen eines Wiki sind zu pauschal. Die meisten genannten Schwächen gibt es bei Confluence als Wiki gar nicht.

Kapitel Acht beginnt sehr vielversprechend mit der Überschrift “Während der Entwicklung dokumentieren”. Ein Gedanke, der gut zu agiler Entwicklung passt. Der Autor schwört uns darauf ein, die Zielgruppen zu kennen. Sehr gut. Weitere wichtige Empfehlungen sind “Kommunizieren und Rückmeldungen einholen”, “Den Überblick behalten” und “Loslassen können”.

Im Kapitel Neun beschreibt der Autor die Architektur von “DokChess”, einem Schachprogramm. Es ist ein geschlossenen Fallbeispiel und zeigt die Anwendung der Empfehlungen und Vorschläge des Autors in diesem Buch. Sehr schwere Kost für die Leser!

Kapitel Zehn sind die Schlussworte des Autors, die er seinen Lesern mitgeben möchte. Er erzählt von Problemen und Fallen und wie man sie umgeht oder entschärft. Leider hat dieses Kapitel nur sechs Seiten.