Ein Werkzeugkasten für den agilen Architekten

Bei einem Blick in die Vergangenheit der Softwareentwicklung lassen sich viele Projekte finden, in denen die Dokumentation der Software und insbesondere der Architektur zu umfangreich, veraltet und nicht adressatengerecht war. Dieses Problem erkannten auch die Autoren des Agilen Manifests und haben dies im zweiten Leitsatz „Funktionierende Software steht über einer umfassenden Dokumentation“ [AgileManifesto] festgehalten.
Leider wurde dieser Leitsatz in der Folge oft falsch interpretiert, sodass die Dokumentation vernachlässigt oder im Extremfall vollständig auf sie verzichtet wurde. Auch wenn der Fokus auf der funktionierenden Software liegt, erachten die Autoren des Agilen Manifests den Aspekt der Dokumentation dennoch als wichtig.

Prinzipien für agile Architekturdokumentation

Wie sieht nun eine gute Architekturdokumentation aus, die den agilen Prinzipien entspricht? Zunächst einmal muss die Architekturdokumentation die tägliche Arbeit des Architekten und Entwicklers unterstützen und nicht als Hindernis angesehen werden. Daher lohnt es sich, einen Blick auf die sieben goldenen Regeln, die Andrew Johnston auf seiner Webseite [GoldenRules] formuliert, zu werfen (siehe Kasten 1).

Bei der Erstellung der Architekturdokumentation muss der Autor – dies kann neben dem Architekten jeder Entwickler sein – den Adressaten vor Augen haben, denn er schreibt die Architekturdokumentation nicht nur für sich, sondern auch immer für andere Beteiligte. Deswegen ist immer die Frage zu stellen, welche Informationen den Leser interessieren und welche für ihn nicht relevant sind. Dabei gilt der Grundsatz, so wenig wie möglich, so viel wie nötig zu dokumentieren, um eine schlanke Architekturdokumentation zu erzielen. Allerdings nützen dem Leser die Informationen wenig, wenn die Architekturdokumentation nicht aktuell ist. Jeder Projektbeteiligte muss daher sich kontinuierlich ergebende Änderungen an Struktur, Anforderungen oder Entscheidungen in der Architekturdokumentation nachziehen. Dies ist eine Teamaufgabe und nicht eine Aufgabe, die allein beim Architekten liegt (siehe Kasten 2).

Somit erfolgt die Bearbeitung der Dokumentation innerhalb des Teams durch mehrere Personen. Diese Tatsache muss bei der Gestaltung des Zugriffs auf die Architekturdokumentation berücksichtigt werden. Insbesondere sollte das Single-Source-Prinzip beachtet werden, das heißt, zu jedem Zeitpunkt darf immer nur eine gültige Version der Architekturdokumentation existieren. Vorteilhaft ist in diesem Zusammenhang die Ablage der Architekturdokumentation im vorhandenen Versionsmanagementsystem.
Neben der Erfüllung des Single-Source-Prinzips ergeben sich daraus weitere Vorteile. So wird der Zugriff auf die Dokumente der Architekturdokumentation durch das Versionsmanagement geregelt und die Architekturdokumentation versioniert. Wird die Architekturdokumentation nah am Code abgelegt, so kann bei jeder Codeänderung geprüft werden, ob eine Anpassung der Architekturdokumentation notwendig ist. Relevant ist dies sicherlich, wenn neue Bausteine hinzukommen oder das Verhalten von bestehenden signifikant geändert wird, zum Beispiel die Erweiterung der Schnittstelle eines Bausteins.
Die Architekturdokumentation besteht in der Regel aus Diagrammen, beschreibenden Texten, Tabellen sowie weiteren Grafiken. Damit die Bearbeitung durch jeden Projektbeteiligten erfolgen kann, müssen die verwendeten Werkzeuge für jeden verfügbar und einfach anwendbar sein. Hilfreich ist dabei die Verwendung eines Standards für die Struktur sowie für die Diagramme.
Eine Architekturdokumentation kann noch so gut sein, sie erfüllt ihren Zweck nicht, wenn sie nicht gefunden und gelesen wird. Daher ist sie auf geeigneten Wegen zu kommunizieren, zum Beispiel durch die Veröffentlichung in modernen Kollaborationswerkzeugen. Unter Umständen sind mehrere Wege zu beschreiten, wenn die Adressaten keinen Zugang zu dem Weg der ersten Wahl haben, zum Beispiel durch Erstellen und Versenden eines PDF-Dokumentes per Mail.

Einbettung in die tägliche Praxis

Die Auflistung der Eigenschaften einer guten Architekturdokumentation ist der erste Schritt. Der deutlich schwierigere Schritt ist die Umsetzung und Einbettung in die tägliche Praxis. Wie bereits beschrieben, erfolgt die Bearbeitung iterativ und kontinuierlich. Bei jeder Diskussion, bei jeder Entscheidung, bei jeder größeren Quellcodeänderung und bei durchgeführten Refactoringmaßnahmen ist zu prüfen, ob dabei für die Architektur relevante Informationen entstanden sind, die es zu dokumentieren gilt.
Diese Prüfschritte sind in die Arbeitsprozesse zu integrieren. Nachdem innerhalb einer Gruppe eine Entscheidung getroffen wurde, ist ein Beteiligter zu bestimmen, welcher die Entscheidung zeitnah dokumentiert. Alle Beteiligten sind im Anschluss über die geänderte Dokumentation zu informieren, sodass sie die Änderungen reviewen und gegebenenfalls Korrekturen vornehmen können.
Vor dem Einchecken von Quellcodeänderungen sollte jeder Entwickler ebenfalls überlegen, welche Anpassungen an der Dokumentation er vornehmen muss, um die Dokumentation mit dem Quellcode synchron zu halten. Die angepasste Dokumentation wird dann zusammen mit dem Quellcode eingecheckt. Die Architekturdokumentation gehört somit neben dem Quellcode und den durchgeführten Modultests zu den Artefakten, die im Codereview geprüft werden.
Eine gute Architekturdokumentation wächst mit der Dauer des Projekts. Beginnend bei der Ermittlung der funktionalen und nichtfunktionalen Anforderungen, begleitend zu den Diskussionen der Lösungsideen und abschließend mit der Beschreibung der finalen Lösung, wird sie fortlaufend ergänzt und verfeinert.

Standards für die Architekturdokumentation

Damit bei der gemeinsamen Arbeit an der Architekturdokumentation eine verbindliche Basis an Regeln und Vorgaben existiert, sollten sich alle Beteiligten vorab auf allgemeingültige Standards verständigen. Hinsichtlich der Gestaltung der Diagramme geht an der Modellierungssprache Unified Modeling Language [UML] (fast) kein Weg vorbei. Diese ist seit Jahren der Standard und wird durch viele Werkzeuge unterstützt, sodass keine Hindernisse für eine einfache Bearbeitung dieser Notation vorliegen.
Doch die Diagramme sind nur die halbe Miete. Ohne eine sinnvolle Strukturierung und Beschreibung nutzen sie dem Betrachter der Architekturdokumentation wenig. Diesem Problem haben sich die bekannten Autoren Gernot Starke und Peter Hruschka seit mehreren Jahren gewidmet und ihre Erfahrungen in eine Vorlage gegossen, welche sie allen Interessierten auf der Webseite arc42 [Arc42] zur Verfügung stellen.
Diese Vorlage besteht aus 12 Schubladen, welche alle wesentlichen Aspekte der Architekturdokumentation abdecken. Diese Schubladen stellen eine Checkliste dar und geben Hinweise zur Gestaltung der Architekturdokumentation. Nicht jede Schublade muss notwendigerweise gefüllt werden, aber es lohnt sich auf jeden Fall, kurz über sie nachzudenken. Falls sie für das Projekt am Anfang nicht relevant ist, kann dies kurz notiert und zu einem späteren Zeitpunkt ergänzt werden, wenn zum Beispiel technische Schulden eingegangen werden müssen.
Abbildung 1 zeigt die 12 Schubladen der arc42-Vorlage. Die ersten drei Schubladen Einführung und Ziele , Randbedingungen und Kontextabgrenzung betreffen Aspekte, mit denen sich das Projektteam am Anfang auseinandersetzt, um die Anforderungen und die gestellte Aufgabe zu verstehen. Sobald eine mögliche Lösung in den Köpfen der Projektmitglieder existiert, kann die Schublade Lösungsstrategie mit Inhalt gefüllt werden.

Die Schubladen  Baustein-, Laufzeit- und Verteilungssicht betrachten das Gesamtsystem aus verschiedenen Blickwinkeln. Die Bausteinsicht zeigt die statische Struktur des Systems, wogegen die Laufzeitsicht die dynamischen Faktoren beleuchtet. Falls das System nicht als Monolith gebaut wird, kann in der Verteilungssicht die Aufteilung der Laufzeitkomponenten auf die vorhandenen Rechner dargestellt werden. Für diese drei Sichten wird zu Beginn eine grobe Skizze erstellt, die im Laufe des Projekts verfeinert wird.
Konzepte, welche für alle Bausteine gelten sollen, finden ihren Platz in der Schublade Konzepte. Dabei ist für jedes Konzept ein eigenes Dokument zu schreiben, welches in anderen Dokumenten bei Bedarf referenziert wird. Beispiele für solch übergreifende Konzepte sind die Themen Logging oder Sicherheit. Für den Fall, dass eigene Muster abseits der bekannten Muster eingesetzt werden, sind diese in einem eigenen Dokument zu dokumentieren.
Ein sehr gutes Hilfsmittel zur Befüllung der Schublade Entwurfsentscheidungensind Architecture Decision Records, welche auf eine Idee von Michael Nygard [Nygard] zurückgehen. In Tabelle 1 sind die Inhalte der Architecture Decision Records beschrieben.

Neben den funktionalen Anforderungen sind in jedem Projekt auch die nichtfunktionalen zu berücksichtigen. Die in der ISO-Norm 25010 definierten Qualitätskriterien für Software können zur Bestimmung der Qualitätsszenarien genutzt werden. Jeder Nutzer der Software hat unterschiedliche nichtfunktionale Anforderungen an die Software. In den Qualitätsszenarien kann er diese anhand von Beispielen konkretisieren (siehe Kasten 3). Der Architekt begleitet den Prozess, indem er die Kategorien der ISO-Norm 25010 erläutert und die entstehenden Szenarien den Unterkategorien zuordnet. Dadurch wird ein Baum – ausgehend von dem Knoten Qualität, über die Haupt- und Unterkategorien bis hin zu den Szenarien als den Blättern des Baums – aufgespannt.

Mögliche Risiken und entstehende technische Schulden können, falls vorhanden, in der Schublade Risiken und technische Schulden gesammelt werden. Zu guter Letzt ist das Sammeln und Erläutern der Begriffe der Anwendungsdomäne in der Schublade Glossar immer eine gute Idee, damit bei der Verwendung der Begriffe keine Missverständnisse aufkommen können. Unterschiedlich interpretierte Begriffe führen immer zu Software, die nicht das macht, was der Anwender sich wünscht.

Formate für die Speicherung

Nachdem die Struktur der Architekturdokumentation geklärt ist, ist eine Antwort auf die Frage nach der Speicherung der Dokumentation zu finden. Die Möglichkeit, die Dokumentation in einer Textverarbeitung zu pflegen, scheidet aus, da bereits erwähnt wurde, dass mehrere Personen – unter Umständen gleichzeitig – an der Dokumentation arbeiten müssen. Eine Alternative ist die Verwendung eines modernen Kollaborationswerkzeugs wie Confluence [Confluence]. Diese ermöglichen neben der Erstellung der Dokumente auch eine Versionierung der Artikel sowie über geeignete Plug-ins auch die Gestaltung von Zeichnungen.
Doch trotz der genannten Vorteile wird an dieser Stelle eine andere Lösung vorgeschlagen, in der die beiden Formate AsciiDoc und PlantUML gemeinsam verwendet werden. AsciiDoc [AsciiDoc] wird zur Erfassung der Struktur und der textlichen Informationen benutzt, ergänzt um PlantUML [PlantUML] für die Gestaltung der UML-Diagramme. Grund für die Entscheidung ist, dass beide Formate alle Informationen in Textform speichern, wodurch die entstehende Architekturdokumentation gemeinsam mit dem Quellcode im Versionsmanagementsystem abgelegt werden kann. Die Architekturdokumentation kann nach dem Einchecken der Dokumente durch den Buildprozess in der gewünschten Form, zum Beispiel PDF oder HTML, bereitgestellt werden.
Auch wenn die Idee der Verwendung eines Kollaborationswerkzeugs für die Erfassung der Dokumente verworfen wurde, wird im Folgenden gezeigt, dass solche Werkzeuge zur Verteilung und Veröffentlichung der Architekturdokumentation genutzt werden können.

Werkzeugkasten

Was benötigt ein Entwickler oder Architekt nun für Werkzeuge, um effektiv und schnell die Architekturdokumentation zu erstellen? Besitzt er nicht die richtigen Werkzeuge für die tägliche Arbeit und treten größere Hürden bei der Erstellung auf, so schwindet die Motivation. Die Bearbeitung wird nach hinten geschoben, denn die Zeiträume für die Erstellung der Software sind eng gesteckt und die Dokumentation wird im Zweifel als verzichtbar angesehen. Dies muss jedoch nicht passieren, denn es gibt genügend verfügbare Hilfsmittel.
Jeder Entwickler und jeder Architekt verwendet heutzutage eine integrierte Entwicklungsumgebung (IDE). Für die gängigen Entwicklungsumgebungen wie Atom, Eclipse, IntelliJ idea oder Visual Studio Code sind passende Plug-ins sowohl für AsciiDoc als auch PlantUML verfügbar, sodass der Ersteller der Architekturdokumentation die Umgebung nicht wechseln muss.
Mit den bisher vorgestellten Werkzeugen kann die Architekturdokumentation erstellt, gespeichert und versioniert werden. Was fehlt, ist der letzte Schritt: die Veröffentlichung. Innerhalb einer Organisation ist die Verwendung eines Kollaborationswerkzeugs ein guter Weg, die Architekturdokumentation allen Interessierten zur Verfügung zu stellen. Dazu fehlt nur noch das Verbindungsglied zwischen den eingecheckten Dokumenten und dem Kollaborationswerkzeug.
Für das oft verwendete Werkzeug Confluence existiert eine solches Bindeglied in Form des Confluence Publisher [Publisher]. Das Werkzeug kann per Hand oder über ein Maven-Plug-in gestartet werden und überträgt die eingecheckten Dokumente in ein oder mehrere Confluence-Seiten. Dazu müssen das Werkzeug konfiguriert und die Ablagestruktur der Dokumente angepasst werden. Abbildung 2 zeigt neben der Ablagestruktur die Konfiguration des Maven-Plug-ins.

Um den Confluence Publisher über das Maven-Plug-in zu nutzen, sind wenige Einstellungen vorzunehmen. Dazu gehören:

• der Root-Ordner für die asciiDoc-Dateien (<asciidocRootFolder>)
• der Zugang zu Confluence (<rootConfluenceUrl>)
• der Bezeichnung des Space in Confluence (<spaceKey>)
• der Schlüssel der Seite in Confluence, unter welcher die neuen Seiten eingefügt werden (<ancesterId>)

Der Benutzername und das Passwort können in der Maven-Konfiguration abgelegt werden. Alternativ kann in der pom-Datei die Id eines Servers (<serverId>) angegeben werden. Die Id spezifiziert den Server, auf dem die Datei settings.xml zu finden ist, in der der Benutzername und das verschlüsselte Passwort abgelegt sind.
Die Ablagestruktur der Dokumente muss der Hierarchie der gewünschten Confluence-Seiten entsprechen, das heißt, zunächst ist das Dokument für die Einstiegsseite in die Architekturdokumentation (top-level.adoc) anzugeben, dann folgen die dieser Seite untergeordneten Dokumente in einem Unterordner (top-level). Analog ist für die weiteren Hierarchieebenen zu verfahren. Zusätzliche Dokumente wie zum Beispiel PlantUML-Dateien werden in einem zusätzlichen Ordner auf der obersten Ebene gesammelt.
Zu beachten ist, dass bei Verwendung von Confluence Publisher nicht alle Eigenschaften von AsciiDoc genutzt werden können. So muss zum Beispiel jede AsciiDoc-Datei, die in einem Dokument inkludiert wird, durch Voransetzen des Unterstrichs gekennzeichnet werden. Für die konkreten Möglichkeiten bei der Verwendung von AsciiDoc in Verbindung mit dem Confluence Publisher sei auf die Dokumentation des Letzteren verwiesen [Publisher]. Dies stellt allerdings kein Hindernis dar, denn für eine sinnvolle Architekturdokumentation müssen nicht alle Möglichkeiten von AsciiDoc ausgereizt werden.

Fazit

Das arc42-Template, die Formate Ascii-Doc und PlantUML, die Plug-ins für die IDEs, das Kollaborationswerkzeug Confluence sowie das Werkzeug Confluence Publisher stellen einen mächtigen Werkzeugkasten für die Entwickler und Architekten bereit, mit dem sie die Architekturdokumentation schlank, iterativ, aktuell, standardisiert und einfach bearbeiten können. Weiterhin kann die Architekturdokumentation nah am Quellcode in der Versionsverwaltung abgelegt werden, sodass das Single-Source-Prinzip ebenfalls erfüllt ist.
Mit diesem Werkzeugkasten werden alle Eigenschaften, die in diesem Artikel gefordert wurden, erfüllt.

Literatur & Links

[AgileManifesto] https://agilemanifesto.org/iso/de/manifesto.html

[Arc42] https://arc42.de/ 

[AsciiDoc] https://asciidoc.org/

[Confluence] https://www.atlassian.com/de/software/confluence 

[GoldenRules] https://www.agilearchitect.org/agile/principles.htm

[Nygard] https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions.html

[PlantUML] https://plantuml.com/de/

[Publisher] https://confluence-publisher.atlassian.net/wiki/spaces/CPD/overview 

[UML] https://www.uml.org/