Suche
Leichtgewichtig bleiben mit Markdown, Git und Co.

Architekturdokumentation mit Entwicklerwerkzeugen

Stefan Zörner, Peter Götz

© Shutterstock/ Weenee

Wohl jeder kennt die Situation: Ein neues Projekt startet, und diesmal wollen wir alles richtig machen. Wir machen uns erste Gedanken über die Architektur des Systems und schreiben unsere Ideen auf. Wir halten fest, was wir mit welchen Technologien, Mustern, Prinzipien, Konzepten etc. lösen wollen. Dazu verwenden wir Word oder unser Wiki. Am Anfang klappt auch alles super. Die ersten Änderungen, die sich während der Entwicklung ergeben, schaffen es noch in die Dokumentation. Doch je älter das Projekt wird und je größer das Team, desto seltener werden Änderungen an der Architektur in der Dokumentation nachgezogen. So passiert am Ende genau das, was wir vermeiden wollten: Die Dokumentation unserer Architektur spiegelt nicht die Realität wider und keiner weiß so genau, welche Teile noch richtig sind und welche nicht mehr.

Warum wird Architektur oft nicht nachhaltig dokumentiert? Softwarearchitektur entsteht heute oft im Team, selten im Kopf eines Einzelnen. Sie wird geprägt durch weitreichende Entscheidungen, etwa zur Strukturierung des Systems oder zur Technologie- und Frameworkauswahl. Architekturdokumentation sollte diese Lösungsansätze nachvollziehbar festhalten, unterstützen beim Entwurf des Systems, bei der Kommunikation im Team und gegenüber Dritten bei der Umsetzung im Code. Über den Sinn und Zweck guter Architekturdokumentation herrscht weitgehend Einigkeit. Sie erleichtert die Einarbeitung neuer Kollegen ins Team und erklärt Zusammenhänge, die sich aus dem Quellcode oft nicht ergeben. Trotzdem wird sie oft stiefmütterlich behandelt und nicht nachhaltig gepflegt. Dafür gibt es unserer Erfahrung nach mehrere Gründe.

So legen viele Teams Architekturdokumentationen in Dokumenten ab, die weit vom Quellcode entfernt sind, beispielsweise in Word-Dateien auf einem Projektverzeichnis oder einem Wiki. Der Entwickler übersieht dann schnell, dass nach einer grundlegenden Änderung der Anwendung auch die Dokumentation der Architektur anzupassen wäre.

Ebenso möglich ist eine unklare Aufgabenverteilung. Zu Beginn eines Projekts ist das Erstellen der Architekturdokumentation oft noch eine explizit zugewiesene Aufgabe. Im Verlauf der Entwicklung fehlt dann oft das Bewusstsein, dass nicht nur Code angefasst werden muss, sondern auch Dokumentation.

Und nicht zuletzt liegt es oft auch daran, dass für die Dokumentation binäre Dateiformate verwendet werden, mit denen es schwierig bis unmöglich ist, Versionen sauber zuzuordnen und gegeneinander zu vergleichen. Oder das Wiki führt zwar Seitenhistorien, aber keine Versionen über alle Seiten hinweg. Das macht die nachhaltige Pflege der Architekturdokumentation zu einer mühsamen Tätigkeit, der man lieber aus dem Weg geht.

Architektur näher an die Umsetzung bringen

Um eine Architekturdokumentation zu strukturieren, empfehlen sich leichtgewichtige Gliederungsvorschläge, die zugleich etwas Orientierung beim Entwurf des Systems bieten. Das Software Guidebook von Simon Brown ist ein schlankes Beispiel dazu, im deutschsprachigen Raum hat sich arc42 von Gernot Starke und Peter Hruschka als Quasistandard etabliert. arc42 stellt eine hervorragende Vorlage für die Dokumentation von Architekturen dar und wird in verschiedenen Formaten angeboten, z. B. als .docx-Datei oder Confluence Space.

Wir nutzen die arc42-Struktur als Beispiel, um Architekturergebnisse näher an die Entwickler zu bringen. Dazu stellen wir Werkzeugketten vor, die Markdown-Dateien verarbeiten, in denen Sie die Inhalte der einzelnen arc42-Kapitel beschreiben. Standardwerkzeuge transformieren sie im Build-Prozess in eine HTML-Dokumentation. Diese Werkzeugkette bietet entscheidende Vorteile:

  • Markdown als reines ASCII-Format stellt kaum Anforderungen an die Entwicklungsumgebung, ein einfacher Texteditor ist das einzige benötigte Werkzeug für das Editieren der Inhalte.
  • Die Inhalte der Dokumentation werden zusammen mit dem Quellcode und anderen Ressourcen im Versionskontrollsystem eingecheckt und sind damit für die Entwickler immer zu Hand.
  • Alle Vorteile eines Versionskontrollsystems sind auch für die Dokumentation der Architektur nutzbar: Änderungsprotokollierung, Wiederherstellung, Versionierung, Branching/Merging.
  • Die Integration in den Build-Prozess sorgt dafür, dass die Architekturdokumentation ein weiteres Artefakt des Softwaresystems ist und damit auf einer Stufe steht mit ausführbaren Binärdateien oder Quellcodedokumentation.
Abb. 1: Bearbeiten von Markdown im MacDown-Editor

Abb. 1: Bearbeiten von Markdown im MacDown-Editor

Die Templates im Überblick

Im Folgenden stellen wir Ihnen zwei konkrete Varianten der oben skizzierten Lösung vor. Beide enthalten bereits vorbereitete Markdown-Dateien pro arc42-Kapitel als Beispiel. Einfache UML-Modelle notieren wir in PlantUML und betten sie als Grafiken in Markdown ein. In größeren Systemen ist es sicher sinnvoll, leistungsfähigere Modellierungswerkzeuge zu verwenden und die daraus exportierten Grafiken in Markdown zu integrieren.

Die Beispielkapitel im Template enthalten zunächst nur die Überschriften und werden nach und nach für die konkrete Systemdokumentation mit Inhalt gefüllt. Dazu verwenden wir die Standardsyntax von Markdown sowie verschiedene von GitHub inspirierte Erweiterungen, beispielsweise für Tabellen, oder die automatische Verlinkung von URLs. Nicht benötigte Kapitel ignorieren wir oder entfernen sie aus dem Template.

Wenn Sie PlantUML für die UML-Modelle verwenden wollen, dann notieren Sie diese als einfache ASCII-Dateien. Die eingebetteten Grafiken werden während des Builds aus diesen Eingabedateien generiert. Hierfür muss die Software Graphviz auf dem Build-System installiert sein. Listing 1 zeigt ein einfaches Beispiel für eine PlantUML-Eingabedatei.

@startuml
class ExampleParent {
    - int number
    # String value
    + method()
}
class ExampleChild {
    # anotherMethod()
}
class ExampleRelation {
    + doIt()
}
ExampleParent <|-- ExampleChild
ExampleChild o-- ExampleRelation : aggregation
@enduml
Abb. 2: Aus Eingabedatei erzeugte Grafik

Abb. 2: Aus Eingabedatei erzeugte Grafik

arc42 mit Gradle

Das erste Template, dem wir uns näher widmen wollen, nutzt Gradle als Build-Werkzeug und JBake für die Transformation von Markdown nach HTML. Die Vorlage verwendet den Gradle Wrapper, um den Build auch ohne externe Gradle-Installation durchführen zu können. Der relevante Verzeichnisbaum wird in Listing 2 dargestellt.

- arc42-gradle/
  - src/
    - arc42-markdown/
    - jbake/
  - build.gradle
  - README.md

Unter src/arc42-markdown/ befindet sich die Dokumentation der Architektur als Sammlung von Markdown-Dateien. Das Unterverzeichnis uml/ enthält die PlantUML-Dateien und die daraus erzeugten Grafiken, damit wir bereits während der Erstellung der Dokumentation verlinkte Bilder korrekt im Markdown-Editor anzeigen können.

Das Verzeichnis src/jbake/ enthält die für JBake nötigen Dateien, um aus dem Markdown-Input eine ansprechende HTML-Site erzeugen zu können. Dazu gehören in assets/ die für das mit Bootstrap implementierte HTML-Gerüst benötigten CSS- und JavaScript-Dateien und Schriftpakete. Hierhin werden aber auch die in Markdown referenzierten Grafiken aus src/arc 42-markdown/ während des Builds kopiert. Unter src/jbake/content legt Gradle die Markdown-Dateien aus src/arc42-markdown/ für die Transformation nach HTML ab. src/jbake/templates enthält die Freemarker-Vorlagen je Seitentyp, die von JBake als Basis für die Transformation verwendet werden. In der Datei jbake.properties befindet sich die Konfiguration für JBake, die festlegt, welche Inhalte erzeugt und welche erweiterten Syntaxmöglichkeiten von Markdown verwendet werden.

Herzstück des Templates zur Steuerung des Build-Prozesses ist die Datei build.gradle. Neben Angaben zur Verwaltung der Abhängigkeiten und Plug-ins werden dort im Wesentlichen drei Tasks definiert, welche die Dokumentation aus den Eingabedaten erzeugen (Listing 3).

def arc42InputDir = 'src/arc42-markdown/'

task generatePlantumlImages(type: JavaExec) {
    main 'net.sourceforge.plantuml.Run'
    classpath configurations.runtime
    // environment GRAPHVIZ_DOT: '/path/to/dot'
    args arc42InputDir + '**/*.puml'

Der Task generatePlantumlImages ruft die PlantUML-Transformation als einfache Java-Anwendung auf und übergibt die Eingabedateien als Kommandozeilenargumente. Falls das benötigte Graphviz-Programm dot nicht im PATH enthalten ist, kann es mit der auskommentierten Zeile aus Listing 3 explizit angegeben werden.

def jbakeDir = 'src/jbake/'

task copyMarkdown(type: Copy) {
    from(arc42InputDir) {
        include '**/*.md'
    }
    into jbakeDir + 'content/'
}

task copyGraphics(type: Copy) {
    from(arc42InputDir) {
        include '**/*.png'
    }
    into jbakeDir + 'assets/'
    includeEmptyDirs = false
}

Listing 4 zeigt einfache Gradle-Copy-Tasks, welche die Markdown-Eingabedateien sowie die Grafikdateien in die korrekten Verzeichnisse kopieren, damit JBake sie verarbeiten kann.

defaultTasks 'generatePlantumlImages', 'copyMarkdown', 'copyGraphics', 'jbake'

Neben den drei beschriebenen Tasks wird noch der Task jbake aus dem gleichnamigen Plug-in in den Default-Tasks eingetragen, um die gesamte Dokumentation über den Aufruf von gradle erzeugen zu können (Listing 5).

Abb. 3: Beispiel des Resultats einer Transformation

Abb. 3: Beispiel des Resultats einer Transformation

arc42 mit Maven

Eine weitere Möglichkeit, die wir neben dem Gradle Template vorstellen möchten, verwendet Maven für den Build. Maven bietet mit dem maven-site-plugin bereits standardmäßig eine Möglichkeit, Dokumentation aus den Inhalten einzelner Maven-Module zu erzeugen.

- arc42-maven/
  - src/site/
    - markdown/
    - plantuml/
    - resources/
    - site.xml
  - pom.xml

Listing 6 zeigt den Verzeichnisbaum des Templates. Das Verzeichnis src/site/markdown enthält die Markdown-Eingabedateien mit der eigentlichen Dokumentation. Unser Beispiel definiert hier noch eine eigene index.md, in der das Template beschrieben wird. Die einzelnen Kapitel befinden sich im Unterverzeichnis doc/ und sind analog zu den Dateien aus dem arc42-gradle Template benannt.

Falls Sie PlantUML verwenden, werden die erzeugten Grafiken im Verzeichnis plantuml/ abgelegt. Während des Build-Prozesses werden sie dann in .png-Grafikdateien umgewandelt und unter resources/images/uml abgelegt, um korrekt in die HTML-Dokumentation eingebunden zu werden. Sie können Grafiken natürlich auch direkt unter resources/images/uml speichern und in Markdown relativ verlinken (Listing 7).

![Beispiel UML-Modell](images/domain-classes.png "Beispiel UML-Modell")

Die pom.xml werden wir nur in Auszügen vorstellen, da dies ansonsten alleine den Umfang des Artikels sprengen würde. Interessant sind sicherlich die Plug-ins, die eingebunden werden, und das sind erstaunlich wenige (Listings 8 und 9). Da wäre zunächst einmal das maven-site-plugin in der Version 3.4. Diese ist bereits in der Lage, ohne weitere zu definierende Abhängigkeiten aus Markdown-Dateien eine Ausgabe in HTML zu erzeugen

  org.apache.maven.plugins
  maven-site-plugin
  3.4

Daneben benötigen wir das plantuml-maven-plugin, das aus den PlantUML-Modellen Grafiken erzeugt.

<plugin>
 <groupId>com.github.jeluard</groupId>
  <artifactId>plantuml-maven-plugin</artifactId>
  <version>1.1</version>
  <configuration>
    <sourceFiles>
      <directory>${basedir}/src/site/plantuml</directory>
      <includes>
        <include>**/*.puml</include>
      </includes>
    </sourceFiles>
    <!--graphvizDot>/path/to/dot</graphvizDot-->
    <outputDirectory>${generatedUmlImagesPath}</outputDirectory>
  </configuration>
  <dependencies>
    <dependency>
      <groupId>net.sourceforge.plantuml</groupId>
      <artifactId>plantuml</artifactId>
      <version>8019</version>
    </dependency>
  </dependencies>
  <executions>
    <execution>
      <id>generate-uml-model-site</id>
      <phase>pre-site

Dies ist kein Standard-Maven-Plug-in, funktioniert aber sehr gut. Es benötigt zur Konfiguration das Verzeichnis, in dem die PlantUML-Eingabedateien liegen, sowie das Ausgabeverzeichnis. Falls das von PlantUML verwendete GraphViz nicht im PATH konfiguriert ist, muss wie bei Gradle der Pfad zum Executable bekannt gemacht werden (siehe auskommentiertes Element graphvizDot in Listing 9). Die einzige Abhängigkeit des Plug-ins ist PlantUML selbst. Zu guter Letzt hängen wir noch die Ausführung des Plug-ins in den Maven-Lebenszyklus ein und fertig ist die Konfiguration der Maven-Plug-ins.

Da wir aus der Maven-Site ein paar für uns irrelevante Inhalte entfernt haben, gibt es noch ein weiteres Plug-in, das wir unter reporting/plugins konfiguriert haben (Listing 10).

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-project-info-reports-plugin</artifactId>
  <version>2.8</version>
  <reportSets>
    <reportSet>
      <reports>
        <report>summary</report>
        <report>project-team</report>
        <report>license</report>
      </reports>
    </reportSet>
  </reportSets>
</plugin>

Damit legen wir fest, dass wir neben der eigentlichen Architekturdokumentation in Markdown nur das Project Summary, die Übersicht über das Projektteam sowie die Lizenzbedingungen, in die Site integrieren wollen. Dies kann natürlich von Projekt zu Projekt angepasst werden.

Neben der pom.xml mit der Beschreibung des Maven-Moduls ist für ein korrektes Funktionieren des Templates auch die Datei src/site/site.xml nötig. In dieser beschreiben wir zunächst, welchen Look and Feel unsere Seite haben soll.

<skin>
  <groupId>org.apache.maven.skins</groupId>
  <artifactId>maven-fluido-skin</artifactId>
  <version>1.3.1</version>
</skin>
<custom>
  <fluidoSkin>
    <sideBarEnabled>true</sideBarEnabled>
    <copyrightClass>pull-right</copyrightClass>
    <gitHub>
      <projectId>p-goetz/arc42-maven</projectId>
      <ribbonOrientation>right</ribbonOrientation>
      <ribbonColor>orange</ribbonColor>
    </gitHub>
  </fluidoSkin>
</custom>

Das Element skin beschreibt dabei ein Maven Site Skin, das das generelle Layout festlegt. Das maven-fluido-skin baut – wie das Gradle Template – auf Bootstrap auf und bringt ein ansprechendes Äußeres und ein responsives Verhalten mit. Dieses Skin haben wir im Element custom noch feiner konfiguriert (Details finden sich in der offiziellen Dokumentation unter http://maven.apache.org/skins/maven-fluido-skin/).

Abb. 4: Beispiel einer erzeugten Maven-Site-Startseite

Abb. 4: Beispiel einer erzeugten Maven-Site-Startseite

Und wie geht es weiter?

Die oben beschriebenen Templates stellen einen möglichen Startpunkt dar, um unser genanntes Ziel zu erreichen: Die Architekturdokumentation näher zu den Entwicklern und dem Softwareentwicklungsprozess zu bringen. Auf ein paar Themen möchten wir aber noch eingehen, um zu zeigen, welche Dinge bei einer Übernahme dieses oder eines ähnlichen Ansatzes in die eigene Projektarbeit zu bedenken sind.

Wir haben für die UML-Modelle in den Templates ein bewusst einfaches Werkzeug wie PlantUML gewählt. Die konsistente Modellierung von Architekturen in verschiedenen Sichten bereitet jedoch am meisten Spaß, wenn man hierzu geeignete Werkzeuge zur Verfügung hat, z. B. Enterprise Architect. Die daraus exportierten Grafiken kommen dann in der Dokumentation zum Einsatz, und die Konfiguration von PlantUML kann aus den Templates entfernt werden. Wir haben das anhand der Dokumentation der Schach-Engine DokChess in GitHub veranschaulicht. Das Beispiel verwendet das Gradle Template und zeigt, dass auch umfangreiche Architekturdokumentation auf diese Art sinnvoll möglich ist.

Eine der Hauptaufgaben des Softwarearchitekten ist es, die Dokumentation im Kreis der Stakeholder zu diskutieren und zu verfeinern sowie Aufklärungsarbeit zu leisten. Die Stakeholder müssen also die Möglichkeit erhalten, die Dokumentation einzusehen. Beim Einsatz unseres Template-Vorschlags und dem automatischen Deployment der Dokumentation, z. B. im Intranet, haben Stakeholder jederzeit Zugriff auf die aktuellste Version. Im direkten Austausch zwischen Architekt und Stakeholdern können dann offene Fragen geklärt und Feedback kann direkt in die Dokumentation eingearbeitet werden.

Lieber gar keine Dokumentation als eine, die nicht mehr aktuell ist. Mit den beschriebenen Templates arbeiten Entwickler mit ihren gewohnten Entwicklungswerkzeugen ohne Kontextwechsel. Bei Änderungen der Architektur im Quelltext passen sie die dazugehörige Dokumentation mit an. Deren Pflege sollte in die Qualitätsziele (z. B. Definition of Done) des Entwicklungsteams aufgenommen werden, damit nötige Änderungen direkt im Entwicklungsprozess eingearbeitet werden. Auch kann die Dokumentation als weiteres Artefakt der Softwareentwicklung den gleichen Review- und Abnahmeprozess durchlaufen (Pair Documenting oder Peer Reviews).

Auch andere haben sich schon mit der Frage nach leichtgewichtigen und entwicklernahen Alternativen zur Dokumentation von Architektur beschäftigt. Hier zwei interessante Beispiele, die Sie auf eigene Faust weiter erkunden können:

Fazit

Architekturdokumentation ist und bleibt wichtig für eine langfristig wart- und erweiterbare Software. Darüber darf auch der folgende, oft missverstandene Satz aus dem agilen Manifest nicht hinwegtäuschen: Working software over comprehensive documentation. Meist wird dabei der wichtige Zusatz übersehen: That is, while there is value in the items on the right, we value the items on the left more.

Es geht also nicht darum, keine Dokumentation mehr zu schreiben, sondern die richtige Art im richtigen Umfang. Und ganz im Sinne der beiden Aussagen oben wollen wir mit diesem Artikel einen Anstoß dazu geben, die richtige Art von Architekturdokumentation zu erzeugen und keine, die erstellt wird, weil das so im Projekthandbuch steht, die aber niemand jemals liest. Wir wünschen viel Freude beim Experimentieren und freuen uns auf Ihr Feedback zu den Templates und Beispielen.

Aufmacherbild: Metal Key von Shutterstock / Urheberrecht:Weenee

Geschrieben von
Stefan Zörner
Stefan Zörner
Von der Bayer AG über IBM und oose zu embarc. Stefan Zörner blickt auf zwanzig Jahre IT-Erfahrung zurück und stets gespannt nach vorn. Er unterstützt in Architektur- und Umsetzungsfragen mit dem Ziel, gute Architekturansätze wirksam in der Implementierung zu verankern. Sein Wissen und seine Erfahrung teilt er regelmäßig in Vorträgen, Artikeln und Workshops. Stefan ist aktives Board-Mitglied im iSAQB und Autor des Buchs „Softwarearchitekturen dokumentieren und kommunizieren“ (Hanser-Verlag, 2. Auflage 2015). Twitter: @StefanZoerner
Peter Götz

Peter Götz  ist IT-Consultant aus Leidenschaft. Als Softwarearchitekt unterstützt er seine Kunden in Softwareentwicklungsprojekten und greift auch selbst noch gerne zur IDE, um die eigenen Architekturideen umzusetzen.

Mail: peter.goetz@pgoetz.de

Kommentare

Hinterlasse einen Kommentar

1 Kommentar auf "Architekturdokumentation mit Entwicklerwerkzeugen"

avatar
400
  Subscribe  
Benachrichtige mich zu: