02 | 2020 public

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://www.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).
Moderne Business-Architekturen | .public 02-20 | 27