Zuerst erschienen in der Ausgabe .public 02-2020
von Dr. Atila Kaya
Beim Thema Architekturdokumentation stellt sich in Softwareprojekten immer wieder eine Reihe von typischen Fragen: Wie und von wem soll die Architektur dokumentiert werden? Wie kann Architekturdokumentation in die Teamarbeit integriert werden und sie unterstützen, um eine qualitativ hochwertige Softwarelösung zu liefern? Wie können Architekturentscheidungen in der Praxis transparent und nachvollziehbar an die Stakeholder werden, und wie kann der Weg für zukünftige Architekturreviews geebnet werden?
Architekturentscheidungen
In der Praxis haben sich Wikis als Werkzeug für die Erstellung sowie die Ablage von Architekturentscheidungen bewährt. Sie bieten gleich mehrere Vorteile: Wiki-Software fördert Transparenz und Kollaboration und bietet komfortable Such- und Verlinkungsmöglichkeiten. Richtig eingesetzt, zum Beispiel durch die Nutzung von Kommentar- und Benachrichtigungsfunktionen, kann Wiki-Software Architekturmanagementprozesse, wie beispielsweise Gremienarbeit, unterstützen.
Eine potenzielle Schwäche bei der Nutzung von Wikis zur Architekturdokumentation ist die unzureichende Unterstützung für die Erstellung und Bearbeitung von Abbildungen und Tabellen. Daher sollte bei der Auswahl der Wiki-Software besonderes Augenmerk auf diese Punkte gelegt werden. Gute Produkte wie Confluence3 oder MediaWiki4 ermöglichen effiziente Erstellung, Bearbeitung und Versionierung von Abbildungen innerhalb des Wikis, zum Beispiel durch sogenannte Plug-ins.
Eine weitere Schwäche von Wikis sind die Exportmöglichkeiten für die Inhalte – wenn zum Beispiel der Inhalt oder ein Teil dessen als eine PDF-Datei mit Inhaltsverzeichnis und entsprechendem Layout für den Druck exportiert werden soll. Abhängig vom Produkt und von den Anforderungen an das Layout des exportierten Dokuments können hier größere Aufwände entstehen.
Die vielleicht größte Schwäche von Wikis für die Architekturdokumentation ist die Versionierung von Inhalten, die zwar von Wiki-Software übernommen wird, allerdings unabhängig von der Versionierung der Software ist. Möchte man Software und Architekturdokumentation gemeinsam versionieren, muss in der Regel mit umständlichen Behelfslösungen gearbeitet werden. Die Ursache dieses Problems ist die fehlende Nähe und Verknüpfung von Dokumentation und Quellcode. Darauf gehen wir im weiteren Verlauf dieses Artikels ein und stellen eine Lösung vor.
Nicht selten herrscht in Projektteams keine klare Vorstellung über Form, Gliederung und Inhalt der notwendigen Dokumentation. Gute Vorlagen für Dokumentationen sind daher sehr wertvoll. Dabei hat sich folgende Struktur als Vorlage für Architekturentscheidungen in der Praxis bewährt (siehe Tabelle nächste Seite):
|
Software-Architektur, Software-Architekt, Architekturentscheidungen und Architekturarbeit Nach Martin Fowler besteht Software-Architektur aus Softwaredesign- Entscheidungen, die sowohl wichtig als auch schwer zu ändern sind – eine Definition, der wir uns anschließen. Wie auch Stefan Zöller nennen wir diese Art von Entscheidungen „Architekturentscheidungen“.1 Unter Architekturarbeit, also dem Erarbeiten der Architektur, verstehen wir zum einen das Entwerfen der Lösung. Zum anderen auch die nachvollziehbare Herleitung von Architekturentscheidungen sowie die Verantwortung für deren Umsetzung. Laut ISAQB, dem International Software Architecture Qualification Board, das sich die Lehre, Aus- und Weiterbildung für Software-Architektur auf die Fahne geschrieben hat, sind die sechs Kernaufgaben der Architekturarbeit wie folgt (siehe Abbildung 1):2 Ein Softwarearchitekt ist derjenige, der die Architekturarbeit ausführt, unabhängig vom Projektvorgehen (klassisch oder agil) und vom Rollenverständnis (expliziter Architekt oder nicht).
|
Tabelle 1: Vorlage für Architekturentscheidungen
Feste Kriterien haben sich in mehreren Projekten als sehr nützlich erwiesen (siehe Abbildung 2). Bei Bedarf kann für jede Architekturentscheidung die Liste um zusätzliche Kriterien erweitert werden.
Architekturüberblick
Für die Dokumentation der Architektur eines Softwaresystems stellt arc42.org ein erprobtes Template in verschiedenen Formaten unter der Lizenz Creative Commons Attribution zur Verfügung.5 Danach wird eine kompakte Architekturdokumentation wie folgt gegliedert (siehe Tabelle 2).
Qualitätsmerkmale sind Anforderungen an das Softwaresystem, die über die etwa in User-Storys beschriebenen fachlichen Funktionalitäten hinausgehen, wie zum Beispiel „Zuverlässigkeit“ oder „Wartbarkeit“. Für die Prüfung von Qualitätsmerkmalen sollte die Prüfung der Einhaltung von Architekturvorgaben im Idealfall automatisiert und kontinuierlich stattfinden. Hierfür stehen mit jQAssistant6 und Neo4J7 Open-Source-Werkzeuge zur Verfügung, die sich mit überschaubarem Aufwand in Continuous Integration(CI) Pipelines integrieren lassen. Die Ergebnisse der Prüfung von Architekturvorgaben können dann mithilfe von Plug-ins in SonarQube8 integriert werden.9 Diese Integration ermöglicht die gemeinsame Betrachtung von Ergebnissen der statischen Codeanalyse und die Prüfung von weiteren Qualitätsmerkmalen in der SonarQube-Plattform.
Abbildung 2: Beispielkriterien für Architekturentscheidungen
Tabelle 2: für kompakte Architekturdokumentationen
Architekturpräsentation
Die nachfolgend skizzierte Situation ist typisch für den Projektalltag: Neue Projektmitglieder oder andere Stakeholder wollen sich einen schnellen Überblick über das Projekt sowie die Lösungsansätze verschaffen. Allerdings finden sie entweder keine Informationen oder aber sehr detaillierte Informationen. Ein Überblick über Projektziele, Herausforderungen und Lösungsansätze auf einer konzeptionellen Ebene fehlt.
Dabei ist die zielgerichtete Kommunikation der Architektur mit geeigneten Mitteln ein wichtiger Faktor für den Projekterfolg. Ein aktueller aus zehn bis fünfzehn Folien bestehender Foliensatz ist eine wertwolle Unterstützung zur Präsentation der Problemstellung und der zentralen Lösungsansätze. Die Architekturpräsentation hat das Ziel, die Informationen aus dem Architekturüberblick in kompakter Form zu wiederzugeben. Hier hat sich folgende Struktur für die Architekturpräsentation in der Praxis bewährt (siehe Tabelle 3):
Tabelle 3: Vorlage für die Strukturierung von Architekturpräsentationen
DOCS-AS-CODE
In den letzten Jahren entstand für die Erstellung der Dokumentation ein neuer Ansatz mit dem Ziel, die fehlende Nähe zwischen Dokumentation und Quellcode durch gut geeignete Werkzeuge herzustellen und dadurch die Motivation von Entwicklungsteams bei der Erstellung und Pflege der Dokumentation zu erhöhen. Für diesen Ansatz hat sich der Begriff „Docs-as-Code“ etabliert.10 Hier wird die Dokumentation in AsciiDoc, einem rein textbasierten Format mit einfacher Syntax, erstellt, analog zu Quellcode in einem Repository verwaltet sowie in den Build- und Testprozess der Software integriert. Die Verwaltung der Dokumentation in einem Repository, wie zum Beispiel git11, ermöglicht die gleichen Workflows für die Dokumentation wie für den Quellcode: Versionierung, Reviews, Branching, Merging usw. Zudem kann mit dem Open-Source-Konverter AsciiDoctor12 die in AsciiDoc erstellte Dokumentation in verschiedene Ausgabeformate wie HTML5, DOCX oder PDF konvertiert werden.
Das in Gradle13 entwickelte Open-Source-Werkzeug docToolchain nutzt AsciiDoctor und Pandoc14 als Konverter und treibt die Automatisierung der Dokumentenerstellung konsequent weiter.15 Hierfür bringt docToolchain eine Reihe von Gradle-Modulen (Tasks) mit, die bei Bedarf auch erweitert werden können. Mit docToolchain können zum Beispiel Diagramme aus Sparx Enterprise Architect (EA)16 oder Tabellen aus MS Excel durch entsprechende Tasks exportiert und in die auf arc42-Vorlage basierende Architekturdokumentation im AsciiDoc-Format eingebunden werden. Dabei unterstützt der Include-Task die Verteilung der Dokumentation auf mehrere Dateien und somit deren Modularisierung. Durch eine gut durchdachte Modularisierung der Dokumentation wird eine bessere Übersichtlichkeit erzielt, die Zusammenarbeit im Team verbessert, und Teile der Dokumentation in verschiedenen Kontexten werden wiederverwendbar gemacht. Darüber hinaus bietet docToolchain weitere Tasks, um die Dokumentation automatisch nach Problemen wie fehlerhaften Links oder fehlenden Bildern zu prüfen.
Abbildung 3: Übersicht der Dokumentenerstellung mit docToolchain
Am Ende der Werkzeugkette wird die Architekturdokumentation im gewünschten Ausgabeformat, wie zum Beispiel als PDF- oder Word-Dokument, generiert. Alternativ kann die Dokumentation in Wiki-Syntax generiert und in Confluence publiziert werden.
Wenn die Dokumentation dem Docs-as-Code-Ansatz folgend im AsciiDoc-Format erstellt und im gewünschten Ausgabeformat generiert wird, dann muss sie auch in AsciiDoc weiter gepflegt werden. Demzufolge profitiert man zwar bei einer generierten Confluence-Seite von Confluence-Features wie zum Beispiel „Suchen“, „Seite beobachten“ oder „Kommentieren“, darf aber die generierte Seite nicht in Confluence editieren.
Mit docToolchain können auch Word-Dokumente in AsciiDoc konvertiert und in den Build-Prozess integriert werden. Deshalb kann es auch in Projekten eingesetzt werden, in denen einige Stakeholder weiterhin mit Word arbeiten. Allerdings hat die automatische Konvertierung von DOCX in AsciiDoc ihre Grenzen, so dass einige formale Vorgaben bei der Erstellung des Word-Dokuments eingehalten werden müssen, um manuelle Schritte vor der Konvertierung zu vermeiden.
Es stellt sich insbesondere für die Architekturdokumentation die Frage, welche Aspekte der Dokumentation besser nah am Quellcode dokumentiert werden sollten. Es empfiehlt sich, diese Entscheidung im Hinblick auf organisatorische und projektspezifische Bedingungen zu treffen und die Dokumentation entsprechend zu modularisieren. Zum Beispiel kann ein Detailkonzept zur Replikation von Datenbankclustern, das von einer anderen Organisationseinheit oder einer externen Firma als Word-Dokument geliefert wird, nach der Konvertierung in die Architekturdokumentation im AsciiDoc-Format eingebunden werden, um am Ende Wiki-Seiten zu generieren und in Confluence zu publizieren.
Fazit
Für die wirkungsvolle Gestaltung der Architekturdokumentation existieren erprobte Vorlagen, die die Form, Struktur sowie mögliche Inhalte vorgeben. Dadurch sinkt die Einstiegshürde für die Erstellung von qualitativ hochwertiger und wirksamer Architekturdokumentation. Die Inhalte müssen dabei zielgruppengerecht ausgesucht und je nach Anlass (zum Beispiel eine Präsentation oder ein Architekturüberblick) unterschiedlich detailliert und kombiniert werden. Es empfiehlt sich insbesondere für agil umgesetzte Projekte, die Architekturdokumentation analog zum Quellcode iterativ und inkrementell zu erstellen. Mit dem Ziel, Aufwände zu reduzieren, kann die Erstellung und Pflege der Dokumentation, dem Docs-as- Code-Ansatz folgend, in den Test- und Releasezyklus der Software eingebunden werden. Für diesen immer populärer werdenden Ansatz existiert mit docToolchain ein ausgereiftes Open-Source- Werkzeug, das die kontinuierliche Erstellung und Pflege der Architekturdokumentation durch die Integration in den Build-Prozess unterstützt. Dadurch wird die Motivation, wirkungsvolle Architekturdokumentation auch ohne explizite Architekturrolle in Teamarbeit zu erstellen, deutlich verbessert. •
1 Stefan Zöllner: Softwarearchitekturen dokumentieren und kommunizieren (2. Auflage). Carl Hanser Verlag 2015, Seite 18.
2 ISAQB: https://www.isaqb.org (abgerufen am 16.02.2020).
3 https://www.atlassian.com/de/software/confluence (abgerufen am 16.02.2020).
4 https://www.mediawiki.org/wiki/MediaWiki (abgerufen am 16.02.2020).
5 arc42: https://arc42.org/ (abgerufen am 16.02.2020).
6 https://jqassistant.org/ (abgerufen am 16.02.2020).
7 https://neo4j.com/ (abgerufen am 16.02.2020).
8 https://www.sonarqube.org/ (abgerufen am 16.02.2020).
10 https://www.writethedocs.org/guide/docs-as-code/ (abgerufen am 16.02.2020).
11 https://git-scm.com/ (abgerufen am 16.02.2020).
12 https://asciidoctor.org/ (abgerufen am 16.02.2020).
13 https://gradle.org/ (abgerufen am 16.02.2020).
14 https://pandoc.org/ (abgerufen am 16.02.2020).
15 https://github.com/docToolchain/docToolchain (abgerufen am 16.02.2020).
16 https://www.sparxsystems.de/ (abgerufen am 16.02.2020).
