WIRKUNGSVOLLE ARCHITEKTURDOKUMENTATION ALS ERFOLGSFAKTOR (NICHT NUR) FÜR AGILE PROJEKTE - msg Systems
←
→
Transkription von Seiteninhalten
Wenn Ihr Browser die Seite nicht korrekt rendert, bitte, lesen Sie den Inhalt der Seite unten
WIRKUNGSVOLLE
ARCHITEKTURDOKUMENTATION
ALS ERFOLGSFAKTOR (NICHT NUR)
FÜR AGILE PROJEKTE
| 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?
22 | .public 02-20 | Moderne Business-ArchitekturenARCHITEKTURENTSCHEIDUNGEN als eine PDF-Datei mit Inhaltsverzeichnis und entsprechendem
Layout für den Druck exportiert werden soll. Abhängig vom Pro-
In der Praxis haben sich Wikis als Werkzeug für die Erstellung dukt und von den Anforderungen an das Layout des exportierten
sowie die Ablage von Architekturentscheidungen bewährt. Sie Dokuments können hier größere Aufwände entstehen.
bieten gleich mehrere Vorteile: Wiki-Software fördert Transpa-
renz und Kollaboration und bietet komfortable Such- und Ver- Die vielleicht größte Schwäche von Wikis für die Architekturdo-
linkungsmöglichkeiten. Richtig eingesetzt, zum Beispiel durch kumentation ist die Versionierung von Inhalten, die zwar von
die Nutzung von Kommentar- und Benachrichtigungsfunktio- Wiki-Software übernommen wird, allerdings unabhängig von
nen, kann Wiki-Software Architekturmanagementprozesse, wie der Versionierung der Software ist. Möchte man Software und
beispielsweise Gremienarbeit, unterstützen. Architekturdokumentation gemeinsam versionieren, muss in
der Regel mit umständlichen Behelfslösungen gearbeitet wer-
Eine potenzielle Schwäche bei der Nutzung von Wikis zur Ar- den. Die Ursache dieses Problems ist die fehlende Nähe und
chitekturdokumentation ist die unzureichende Unterstützung Verknüpfung von Dokumentation und Quellcode. Darauf gehen
für die Erstellung und Bearbeitung von Abbildungen und Tabel- wir im weiteren Verlauf dieses Artikels ein und stellen eine Lö-
len. Daher sollte bei der Auswahl der Wiki-Software besonderes sung vor.
Augenmerk auf diese Punkte gelegt werden. Gute Produkte wie
Confluence3 oder MediaWiki4 ermöglichen effiziente Erstellung, Nicht selten herrscht in Projektteams keine klare Vorstellung
Bearbeitung und Versionierung von Abbildungen innerhalb des über Form, Gliederung und Inhalt der notwendigen Dokumen-
Wikis, zum Beispiel durch sogenannte Plug-ins. tation. Gute Vorlagen für Dokumentationen sind daher sehr
wertvoll. Dabei hat sich folgende Struktur als Vorlage für Ar-
Eine weitere Schwäche von Wikis sind die Exportmöglichkeiten chitekturentscheidungen in der Praxis bewährt (siehe Tabelle
für die Inhalte – wenn zum Beispiel der Inhalt oder ein Teil dessen nächste Seite):
Software-Architektur, Software-Architekt, Architekturentscheidungen und Architekturarbeit
Nach Martin Fowler besteht Software-Architektur aus Softwaredesign- Anforderungen und
Entscheidungen, die sowohl wichtig als auch schwer zu ändern sind – Randbedingungen
klären
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
Strukturen Querschnittliche
wir zum einen das Entwerfen der Lösung. Zum anderen auch die nach- entwerfen Konzepte
vollziehbare Herleitung von Architekturentscheidungen sowie die Verant- entwerfen
wortung für deren Umsetzung. Laut ISAQB, dem International Software
Architecture Qualification Board, das sich die Lehre, Aus- und Weiterbil-
dung für Software-Architektur auf die Fahne geschrieben hat, sind die
Architektur
sechs Kernaufgaben der Architekturarbeit wie folgt (siehe Abbildung 1):2 Umsetzung
kommunizieren Architektur
begleiten
bewerten
Ein Softwarearchitekt ist derjenige, der die Architekturarbeit ausführt,
unabhängig vom Projektvorgehen (klassisch oder agil) und vom Rollen-
Abbildung 1: Sechs Kernaufgaben der Architekturarbeit
verständnis (expliziter Architekt oder nicht).
Moderne Business-Architekturen | .public 02-20 | 23ABSCHNITT BESCHREIBUNG
Fragestellung Problembeschreibung, Relevanz für die Architektur
Einflussfaktoren Randbedingungen, Qualitätsziele, betroffene Risiken
Annahmen Getroffene Annahmen, neue Risiken
Alternativen Beschreibung der Lösungsoptionen, ausgeklammerte Lösungsoptionen
Kriterien Feste Kriterien, zusätzliche Kriterien
Tabellarische Bewertung der Alternativen im Hinblick auf Kriterien, Zusammenfassung der
Entscheidung und Begründung
Entscheidung mit kurzer Begründung
Auswirkungen Nennenswerte Auswirkungen auf andere Entscheidungen und auf die Strategie
Zugehörige Entscheidungen Weitere Entscheidungen, die im Zusammenhang stehen
Tabelle 1: Vorlage für Architekturentscheidungen
Feste Kriterien haben sich in mehreren Projekten als sehr Danach wird eine kompakte Architekturdokumentation wie folgt
nützlich erwiesen (siehe Abbildung 2). Bei Bedarf kann für jede gegliedert (siehe Tabelle 2).
Architekturentscheidung die Liste um zusätzliche Kriterien er-
weitert werden. Qualitätsmerkmale sind Anforderungen an das Softwaresys-
tem, die über die etwa in User-Storys beschriebenen fachlichen
Funktionalitäten hinausgehen, wie zum Beispiel „Zuverlässig-
ARCHITEKTURÜBERBLICK keit“ oder „Wartbarkeit“. Für die Prüfung von Qualitätsmerkma-
len sollte die Prüfung der Einhaltung von Architekturvorgaben
Für die Dokumentation der Architektur eines Softwaresystems im Idealfall automatisiert und kontinuierlich stattfinden. Hier-
stellt arc42.org ein erprobtes Template in verschiedenen Forma- für stehen mit jQAssistant6 und Neo4J7 Open-Source-Werk-
ten unter der Lizenz Creative Commons Attribution zur Verfügung. 5
zeuge zur Verfügung, die sich mit überschaubarem Aufwand in
Erweiterbarkeit
Komplexität
Architekturelle Kriterien
Strategie
Security
Hardware
Performance
KRITERIEN Betriebliche Kriterien Testbarkeit
Wartbarkeit
Stabilität
Laufende Aufwände
Wirtschaftliche Kriterien Lizenzsituation
Laufende Kosten
Abbildung 2: Beispielkriterien für Architekturentscheidungen
24 | .public 02-20 | Moderne Business-ArchitekturenKAPITEL BESCHREIBUNG
Einführung und Ziele Aufgabenstellung, Qualitätsziele, Stakeholder
Randbedingungen Wichtigste Vorgaben, die einzuhalten sind
Kontextabgrenzung Fachlicher Kontext, technischer Kontext
Lösungsstrategie Architekturziele mit zugeordneten Architekturansätzen, Verweise auf Details der Lösung
Bausteinsicht Statische Sicht auf die Systemstruktur: Whitebox-Gesamtsystem, Ebene 2 und Ebene 3
Das Verhalten des Systems zur Laufzeit: Ablaufdiagramme für die wichtigsten Aspekte des
Laufzeitsicht
Systems
Verteilung des Systems: Beschreibung der Laufzeitumgebung, Zuordnung von Bausteinen zu
Verteilungssicht
Deployment Units, Zuordnung der Deployment Units auf die Zielumgebung
Technische, übergreifende Konzepte wie zum Beispiel Persistenz, Caching oder
Querschnittliche Konzepte
Fehlerbehandlung
Entwurfsentscheidungen Architekturentscheidungen
Präzisierung von Qualitätsmerkmalen in konkreten Szenarien, Zuordnung der Szenarien zu
Qualitätsanforderungen
Merkmalen in einem Qualitätsbaum
Risiken und technische Risiken, die die Architekturentscheidungen beeinflusst haben. Bewusst oder unbeabsichtigt
Schulden eingegangene Qualitätskompromisse
Glossar Klärung wichtiger Begriffe zur Etablierung eines gemeinsamen Wortschatzes im Projekt
Tabelle 2: für kompakte Architekturdokumentationen
Continuous Integration(CI) Pipelines integrieren lassen. Die eine wertwolle Unterstützung zur Präsentation der Problem-
Ergebnisse der Prüfung von Architekturvorgaben können dann stellung und der zentralen Lösungsansätze. Die Architektur-
mithilfe von Plug-ins in SonarQube8 integriert werden.9 Diese Inte- präsentation hat das Ziel, die Informationen aus dem Archi-
gration ermöglicht die gemeinsame Betrachtung von Ergebnissen tekturüberblick in kompakter Form zu wiederzugeben. Hier hat
der statischen Codeanalyse und die Prüfung von weiteren Quali- sich folgende Struktur für die Architekturpräsentation in der
tätsmerkmalen in der SonarQube-Plattform. Praxis bewährt (siehe Tabelle 3):
ARCHITEKTURPRÄSENTATION
ABSCHNITT INHALTE
Die nachfolgend skizzierte Situation ist typisch für den Projekt-
alltag: Neue Projektmitglieder oder andere Stakeholder wollen Fachlicher Überblick, Ziele, Kontext,
Problemstellung
Randbedingungen
sich einen schnellen Überblick über das Projekt sowie die Lö-
sungsansätze verschaffen. Allerdings finden sie entweder keine Architekturprinzipien, eingesetzte
Lösungsstrategie
Produkte und Technologien
Informationen oder aber sehr detaillierte Informationen. Ein Über-
blick über Projektziele, Herausforderungen und Lösungsansätze Struktur, Verhalten und Verteilung des
Details der Lösung
auf einer konzeptionellen Ebene fehlt. Systems
Nächste Schritte, weiterführende
Ausblick
Dabei ist die zielgerichtete Kommunikation der Architektur mit Informationen
geeigneten Mitteln ein wichtiger Faktor für den Projekterfolg. Ein
aktueller aus zehn bis fünfzehn Folien bestehender Foliensatz ist Tabelle 3: Vorlage für die Strukturierung von Architekturpräsentationen
Moderne Business-Architekturen | .public 02-20 | 25DOCS-AS-CODE Das in Gradle13 entwickelte Open-Source-Werkzeug docToolchain
nutzt AsciiDoctor und Pandoc14 als Konverter und treibt die Auto-
In den letzten Jahren entstand für die Erstellung der Dokumenta- matisierung der Dokumentenerstellung konsequent weiter.15
tion ein neuer Ansatz mit dem Ziel, die fehlende Nähe zwischen Hierfür bringt docToolchain eine Reihe von Gradle-Modu-
Dokumentation und Quellcode durch gut geeignete Werkzeuge len (Tasks) mit, die bei Bedarf auch erweitert werden können.
herzustellen und dadurch die Motivation von Entwicklungs- Mit docToolchain können zum Beispiel Diagramme aus Sparx
teams bei der Erstellung und Pflege der Dokumentation zu er- Enterprise Architect (EA)16 oder Tabellen aus MS Excel durch
höhen. Für diesen Ansatz hat sich der Begriff „Docs-as-Code“ entsprechende Tasks exportiert und in die auf arc42-Vorlage
etabliert.10 Hier wird die Dokumentation in AsciiDoc, einem rein basierende Architekturdokumentation im AsciiDoc-Format
textbasierten Format mit einfacher Syntax, erstellt, analog zu eingebunden werden. Dabei unterstützt der Include-Task die
Quellcode in einem Repository verwaltet sowie in den Build- und Verteilung der Dokumentation auf mehrere Dateien und somit
Testprozess der Software integriert. Die Verwaltung der Doku- deren Modularisierung. Durch eine gut durchdachte Modulari-
mentation in einem Repository, wie zum Beispiel git , ermöglicht
11
sierung der Dokumentation wird eine bessere Übersichtlichkeit
die gleichen Workflows für die Dokumentation wie für den Quell- erzielt, die Zusammenarbeit im Team verbessert, und Teile der
code: Versionierung, Reviews, Branching, Merging usw. Zudem Dokumentation in verschiedenen Kontexten werden wiederver-
kann mit dem Open-Source-Konverter AsciiDoctor die in Asci- 12
wendbar gemacht. Darüber hinaus bietet docToolchain weitere
iDoc erstellte Dokumentation in verschiedene Ausgabeformate Tasks, um die Dokumentation automatisch nach Problemen wie
wie HTML5, DOCX oder PDF konvertiert werden. fehlerhaften Links oder fehlenden Bildern zu prüfen.
JIRA
arc42
Vorlage
Git
leitet ab
Sparx EA
publish
Model HTML5
Artefakte Haupt- Confluence
• Open issues dokument
export include in AsciiDoc generate
• Change Logs
PDF
• Bilder
Visio • Text Word
Model convert Dokument
HTML5
EPub
Datei
Excel-
Datei
Power-
Point-
Datei
docToolchain
Weitere
Export Ascii
Tasks Pandoc
Gradle Doctor
(include,
Tasks
publish usw.)
Abbildung 3: Übersicht der Dokumentenerstellung mit docToolchain
26 | .public 02-20 | Moderne Business-ArchitekturenAm Ende der Werkzeugkette wird die Architekturdokumentation FAZIT
im gewünschten Ausgabeformat, wie zum Beispiel als PDF- oder
Word-Dokument, generiert. Alternativ kann die Dokumentation Für die wirkungsvolle Gestaltung der Architekturdokumentation
in Wiki-Syntax generiert und in Confluence publiziert werden. existieren erprobte Vorlagen, die die Form, Struktur sowie mögliche
Inhalte vorgeben. Dadurch sinkt die Einstiegshürde für die Erstellung
Wenn die Dokumentation dem Docs-as-Code-Ansatz folgend im von qualitativ hochwertiger und wirksamer Architekturdokumenta-
AsciiDoc-Format erstellt und im gewünschten Ausgabeformat tion. Die Inhalte müssen dabei zielgruppengerecht ausgesucht und
generiert wird, dann muss sie auch in AsciiDoc weiter gepflegt je nach Anlass (zum Beispiel eine Präsentation oder ein Architektu-
werden. Demzufolge profitiert man zwar bei einer generierten rüberblick) unterschiedlich detailliert und kombiniert werden.
Confluence-Seite von Confluence-Features wie zum Beispiel
„Suchen“, „Seite beobachten“ oder „Kommentieren“, darf aber die Es empfiehlt sich insbesondere für agil umgesetzte Projekte, die
generierte Seite nicht in Confluence editieren. Architekturdokumentation analog zum Quellcode iterativ und in-
krementell zu erstellen. Mit dem Ziel, Aufwände zu reduzieren,
Mit docToolchain können auch Word-Dokumente in AsciiDoc kann die Erstellung und Pflege der Dokumentation, dem Docs-as-
konvertiert und in den Build-Prozess integriert werden. Deshalb Code-Ansatz folgend, in den Test- und Releasezyklus der Software
kann es auch in Projekten eingesetzt werden, in denen einige eingebunden werden. Für diesen immer populärer werdenden
Stakeholder weiterhin mit Word arbeiten. Allerdings hat die au- Ansatz existiert mit docToolchain ein ausgereiftes Open-Source-
tomatische Konvertierung von DOCX in AsciiDoc ihre Grenzen, so Werkzeug, das die kontinuierliche Erstellung und Pflege der Archi-
dass einige formale Vorgaben bei der Erstellung des Word-Do- tekturdokumentation durch die Integration in den Build-Prozess
kuments eingehalten werden müssen, um manuelle Schritte vor unterstützt. Dadurch wird die Motivation, wirkungsvolle Architek-
der Konvertierung zu vermeiden. turdokumentation auch ohne explizite Architekturrolle in Team-
Es stellt sich insbesondere für die Architekturdokumentati-
arbeit zu erstellen, deutlich verbessert. •
on die Frage, welche Aspekte der Dokumentation besser nah
am Quellcode dokumentiert werden sollten. Es empfiehlt sich, 1 tefan Zöllner: Softwarearchitekturen dokumentieren und kommunizieren (2.
S
Auflage). Carl Hanser Verlag 2015, Seite 18.
diese Entscheidung im Hinblick auf organisatorische und pro- 2 ISAQB: https://www.isaqb.org (abgerufen am 16.02.2020).
3 https://www.atlassian.com/de/software/confluence (abgerufen am 16.02.2020).
jektspezifische Bedingungen zu treffen und die Dokumentation
4 https://www.mediawiki.org/wiki/MediaWiki (abgerufen am 16.02.2020).
entsprechend zu modularisieren. Zum Beispiel kann ein Detail- 5 arc42: https://www.arc42.org/ (abgerufen am 16.02.2020).
6 https://jqassistant.org/ (abgerufen am 16.02.2020).
konzept zur Replikation von Datenbankclustern, das von einer 7 https://neo4j.com/ (abgerufen am 16.02.2020).
8 https://www.sonarqube.org/ (abgerufen am 16.02.2020).
anderen Organisationseinheit oder einer externen Firma als
10 https://www.writethedocs.org/guide/docs-as-code/ (abgerufen am 16.02.2020).
Word-Dokument geliefert wird, nach der Konvertierung in die 11 https://git-scm.com/ (abgerufen am 16.02.2020).
12 https://asciidoctor.org/ (abgerufen am 16.02.2020).
Architekturdokumentation im AsciiDoc-Format eingebunden 13 https://gradle.org/ (abgerufen am 16.02.2020).
14 https://pandoc.org/ (abgerufen am 16.02.2020).
werden, um am Ende Wiki-Seiten zu generieren und in Confluence
15 https://github.com/docToolchain/docToolchain (abgerufen am 16.02.2020).
zu publizieren. 16 https://www.sparxsystems.de/ (abgerufen am 16.02.2020).
Moderne Business-Architekturen | .public 02-20 | 27Sie können auch lesen
