docToolchain besteht aus einer Sammlung von Skripten, die das Erstellen und Pflegen technischer Dokumentation erleichtern. Das Projekt möchte die Hürde niedrig halten, um einfaches, redundanzfreies und modernes Dokumentieren parallel zur eigentlichen Softwareentwicklung zu ermöglichen.
von Falk Sippach
Das Dokumentieren – zum Beispiel der Softwarearchitektur – ist wichtig, wird aber häufig vernachlässigt. Documentation as Code will Entwicklern bzw. mitkodierenden Architekten (wieder) mehr Freude an dieser sonst eher lästigen Tätigkeit bereiten und bessere sowie vor allem aktuelle Ergebnisse erzeugen. Dabei ist die Grundidee, die Dokumentation wie Quellcode zu behandeln:
- Erstellung der Inhalte in leichtgewichtigen Textformaten
- Ablage und Versionierung in Repos (Git, …) nahe beim Source Code
- Einsatz leichtgewichtiger Tools ohne Kontextwechsel
- Integration in die tagtäglich verwendeten Entwicklerwerkzeuge (IDEs)
- Einfache Automatisierung bei der Erstellung der Dokumentationsartefakte
- Inhalte aus vorhandenen Modellen über Generatoransätze integrieren
- kollaboratives Bearbeiten und Einbindung in Reviewprozesse
Um all diese Punkte umzusetzen, gibt es bereits verschiedene Tools sowie auch Erweiterungen in bestehende Build-Management-Werkzeuge. Mit etwas Aufwand kann man sich so seine eigene, individuelle Toolchain zusammenstellen.
docToolchain hingegen kommt bereits als einsatzbereite, vorkonfigurierte Menge diverser Skripte, die die Erzeugung und Wartung technischer Dokumentation zum Kinderspiel machen. Dabei kann docToolchain aber auch sehr einfach an die jeweiligen Bedürfnisse angepasst werden.
Das Projekt startete etwa 2015 mit einem Groovy-Skript, um AsciiDoc-Inhalte nach Confluence zu exportieren. Daraus ist mittlerweile eine große Sammlung von Gradle-Plug-ins, Tasks und die Integration in bestehende Lösungen entstanden. Während in der Version 1.x die Bedienung noch direkt über das Build-Tool Gradle erfolgte, wird mit 2.x (seit September 2021) die Verwendung von docToolchain mittlerweile hinter dem für alle gängigen Betriebssysteme verfügbaren Skript dtcw (docToolchain Wrapper) versteckt, und so werden die Installation und Bedienung stark vereinfacht.
Installation
Auf der Webseite gibt es einige Tutorials zur initialen Einrichtung und grundlegenden Verwendung. Je nach Betriebssystem muss ein Shellskript (für Linux, MacOS oder WSL2 unter Windows), eine PowerShell- oder eine Batch-Datei (beides Windows) heruntergeladen und ausführbar gemacht werden:
cd <doc-project>
curl -Lo dtcw doctoolchain.github.io/dtcw
chmod +x dtcw
Dieses Skript kann direkt im Root-Verzeichnis des Dokumentationsprojekts abgelegt und von dort jederzeit aufgerufen werden. Bei der ersten Ausführung werden einige Voraussetzungen geprüft und ggf. Teile nachinstalliert (z. B. Gradle und docToolchain selbst). Nur Java (aktuell JDK 11 empfohlen) muss bereits vorher installiert sein.
Ist auf dem Rechner der Docker Daemon installiert, wird docToolchain sogar ohne jegliche Eingriffe in das lokale System direkt in einem Docker-Container ausgeführt. Durch den Kommandozeilenparameter –local kann aber die lokale Nutzung erzwungen werden.
##docToolchain Wrapper (dtcw) Nachfolgend sind die wichtigsten Befehle aufgelistet, um mit docToolchain ein neues Dokumentationsprojekt zu starten und verschiedene Ergebnisartefakte zu erzeugen (Tabelle 1). Unter der Haube kommt das Gradle-AsciiDoctor-Plug-in zum Einsatz. Aus den *.adoc-Dateien werden HTML-Seiten oder PDFs erzeugt. Mit AsciiDoc hat man eine einfache, aber auch sehr mächtige Syntax für anspruchsvolle Dokumentationsvorhaben an der Hand.
| Task | Beschreibung |
|---|---|
| ./dtcw tasks –group=doctoolchain | Anzeigen aller verfügbaren Tasks |
| ./dtcw downloadTemplate | Download und Einrichten des arc42-Templates |
| ./dtcw generateHTML | Erzeugen der Ausgabe als Single-Page HTML |
| ./dtcw generatePDF | Erzeugen der Ausgabe als PDF mit ToC (Table of Content) |
| ./dtcw generateSite | Erzeugen einer gesamten (statischen) Micro-Website mit jBake |
Tabelle 1: Typische Befehle von docToolchain
Ein mit downloadTemplate initial erzeugtes Projekt sieht aus, wie in Abbildung 1 gezeigt. Im Unterordner src/docs/arc42 befindet sich eine Vielzahl von AsciiDoc-Dateien, je eine für jedes Kapitel des arc42-Dokumentations-Templates. Diese Struktur lässt sich aber natürlich nach Belieben anpassen und auch um weitere Dokumente erweitern. Die dafür notwendige Konfiguration kann direkt in der im gleichen Verzeichnis befindlichen Datei docToolchainConfig.groovy individuell vorgenommen werden.
Abb. 1: Verzeichnisstruktur eines typischen Dokumentationsprojekts
docToolchain verwendet standardmäßig das AsciiDoc-Format mit dem AsciiDoctor-Konverter. Im Vergleich zum ebenfalls sehr weit verbreiteten Markdown bringt es bereits viele, gerade für technische Dokumentation sinnvolle Features wie Tabellen, Includes, TOC usw. direkt out of the box mit. Man kann docToolchain allerdings auch mit Markdown-Dokumenten verwenden oder mit eigenen Erweiterungen viele andere Inputformate integrieren. Grafiken können sowohl als Binärdateien (JPG, PNG, …), als auch über Textformate (Diagrams as Code: PlantUML, Mermaid.js, …) eingebunden werden. Einer Bearbeitung der Dateien in der Entwicklungsumgebung (IntelliJ IDEA, Visual Studio Code, Eclipse, …) steht dank umfangreicher Plug-ins (Rendern, Preview, Einbetten von Grafiken, …) nichts im Wege und man vermeidet unnötige Kontextwechsel beim Umschalten auf andere (WYSIWYG-)Tools, wie Word, Visio oder Wikis wie Confluence.
Die Ausgaben können an notwendige Unternehmensvorgaben (Corporate Identity: Logo, Styling, Schriftarten, …) angepasst werden. Die Ergebnisse landen im Unterordner build und können jederzeit neu erzeugt werden. Ein Build-Server (Jenkins, …) wird somit bei jedem Commit eines Entwicklers neben der Kompilierung des Quellcodes und der Ausführung der Tests auch immer die Dokumentation frisch bauen und an einem zentralen Ort ablegen. Somit müssen keine Dokumente (Word-Dateien, PDFs, …) mehr per E-Mail herumgeschickt werden. Ein Link auf den Ablageort reicht, und die Leser:innen können sich jederzeit die neueste Fassung anschauen bzw. herunterladen.
Typische Arbeitsweise
Da die Dokumentation bei Docs as Code nahe beim Quellcode liegt und aus leichtgewichtigen Textdokumenten besteht, lässt sich die Arbeit daran sehr einfach in den Entwicklungsalltag integrieren. Um unnötiger Redundanz vorzubeugen, können beispielsweise aus vorhandenen Informationen (Datenbankmodell, Quellcode, UML-Diagramme, …) Teile der Dokumentation einfach generiert und somit mit Leichtigkeit aktuell gehalten werden. So lässt sich aus den AsciiDoc-Dateien sehr einfach und komfortabel Source Code referenzieren. Ändert sich der Quellcode, wird direkt bei der nächsten Erzeugung der Dokumentation die Änderung entsprechend aktualisiert.
DocToolchain bringt zudem einige vordefinierte Eingabeschnittstellen mit. So kann man beispielsweise Inhalte aus Excel-Tabellen als CSV oder sogar direkt als AsciiDoc exportieren, um sie dann über Inkludierung in die bestehende Dokumentation zu integrieren. Ein Anwendungsfall könnte sein, dass der Fachbereich Abnahmekriterien für User Stories in einer Excel-Tabelle pflegt und diese auch regelmäßig aktualisiert und wiederum als XLS-Datei weiterleitet. Diese Inhalte können mitsamt den Formatierungen (Spaltenbreiten, Col- und Row-Span, Farben, …) übernommen werden. Der zugehörige Task heißt exportExcel.
Auf ähnliche Art und Weise lassen sich vorhandene Visio- oder PowerPoint-Inhalte als Grafiken exportieren und dann aus den Ascii-Dokumenten heraus referenzieren. Auch hier wird bei Änderungen an den Originaldateien einfach ein Update generiert, und das ohne jegliche fehlerträchtige Handarbeit.
Ebenfalls sehr beliebt, da gerade bei Großunternehmen in großen Mengen vorhanden, sind die Exporte von Informationen aus dem UML-Modellierungswerkzeug Enterprise Architect. Hier können sowohl die verschiedenen Diagramme als Bilddateien als auch die Notizen als Texte extrahiert und dann in die bestehenden AsciiDoc-Dateien eingebettet werden. Somit lassen sich z. B. vorhandenen Baustein- (Komponentendiagramme etc.) oder Laufzeitsichten (Sequenzdiagramme etc.) einbinden und gleich noch um eine tabellarische Beschreibung der einzelnen Elemente (Notizen des UML-Modells) ergänzen. Auch hier gilt wieder: Ändert sich etwas am Original, wird durch die erneute Erstellung der Dokumentationsartefakte der aktuelle Stand ohne jegliche manuelle Arbeit erzeugt. Weitere Eingabequellen sind:
- Jira (z. B. erledigte Tasks für die Release Notes)
- Git Repositories (exportChangeLog und exportContributors)
- OpenAPI-Schnittstellenbeschreibungen
Alle Skripte werden in der Dokumentation ausführlicher erläutert [8]. In Abbildung 2 sind auf der linken Seite die verschiedenen Eingabemöglichkeiten aufgeführt. Die Beschriftung der Pfeile enthält die Namen der Tasks. Sie beginnen alle mit export, weil sie Informationen aus anderen Formaten und Werkzeugen exportieren, die dann wiederum in die eigentlichen Dokumentationsdateien (*.adoc) eingebettet werden können.
Abb. 2: Überblick zu den docToolchain-Tasks (Quelle)
Ausgabeformate
Das Schaubild zeigt auch die verschiedenen Möglichkeiten, die docToolchain beim Erstellen der Dokumentation bereithält. Neben den Klassikern (HTML, PDF) lassen sich über das DocBook-Format aber auch Word-Dokumente bzw. EPUB-Dateien und sogar mit Reveal.js gebaute Präsentationen erstellen.
Technisch gibt es wenige Grenzen, aber auch inhaltlich kann man sich sehr einfach und frei verschiedene Ausgabedokumente zusammenstellen. Dazu muss man nur mehrere Root-AsciiDoc-Dateien erstellen, die wiederum die entsprechenden modular aufgebauten Texte inkludieren und so rekombinieren. Somit lassen sich nach Zielgruppe maßgeschneiderte Informationen zusammenstellen, unnötiger und häufig redundanter Ballast entfällt.
Und das Killerfeature bei den Ausgabeformaten ist der publishToConfluence-Task. Das kommerzielle Wiki der Firma Atlassian ist aktuell aus kaum einer IT-Abteilung wegzudenken und hat sich zum De-facto-Standard entwickelt. Es wird sehr häufig auch für die Erstellung und Pflege der technischen Dokumentation eingesetzt. An Confluence-Seiten kann man gut gemeinsam arbeiten, insbesondere auch mit nicht so technikaffinen Kollegen (z. B. aus dem Fachbereich). Doch obwohl es gute Strukturierungsmöglichkeiten und eine gut funktionierende Suche gibt, findet man häufig wichtige Informationen nicht so ohne Weiteres wieder. Passend dazu hört man häufiger das folgende treffende Zitat eines unbekannten Autors: „Das Wiki ist der Ort, wo die Dokumente zum Sterben hingehen.“
Durch publishToConfluence können nun beide Welten zusammengebracht werden. Die Entwickler und Architekten schreiben ihre Dokumentation in leichtgewichtigen Text- und Grafikformaten nach dem Docs- und Diagrams-as-Code-Ansatz. Durch den Export nach Confluence stehen die Ergebnisse den anderen Personengruppen lesend zur Verfügung. Diese können sogar die Kommentarfunktion des Wikis nutzen, um Feedback im Rahmen von Reviewprozessen zu geben. Änderungen in Confluence dürfen allerdings nicht gemacht werden bzw. werden beim nächsten Export wieder überschrieben.
Ausblick
docToolchain ist in den letzten Jahren eine sehr beliebte Hilfe im Umfeld von Documentation as Code geworden. Während in Version 1.x bei der Verwendung noch sehr stark die enge Verknüpfung mit dem Build-Management-Tool Gradle zu sehen war, gibt es nun seit 2.x mit dem vor wenigen Monaten entstandenen Wrapper eine bessere Entkopplung. Zukünftig soll Gradle ganz aus docToolchain verschwinden. Da es nun meist unsichtbar unter der Haube werkelt, lässt sich docToolchain mittlerweile auch leichter mit anderen Tools (z. B. Entwicklungsprojekte in Maven) bzw. in ganz anderen Umgebungen (auch außerhalb der Java-Welt) einsetzen.
Neben dem sehr nützlichen Wrapper hat sich in Version 2.x noch einiges mehr getan. Durch die Ausführung von docToolchain in einem Docker-Container kann man sich die kompletten Aufwände für eine lokale Installation aller Abhängigkeiten sparen. Die automatische Installation des arc42-Templates erleichtert zudem den Start eines neuen Dokumentationsprojekts. Und mit jBake wurde ein auf Java basierender, statischer Seitengenerator integriert, um Micro-Websites zum Beispiel als Einstieg in einen Architekturüberblick zu erzeugen. Auch hier sind das Design und Layout flexibel auf die betrieblichen Anforderungen und eigenen Wünsche anpassbar.
Das Open-Source-Projekt unter der Leitung von Ralf D. Müller entwickelt sich beständig weiter. An die 50 Committer haben bereits dazu beigetragen. Ein Teil der verfügbaren Export- und Generierungs-Tasks wurde von der Community beigesteuert. Aktuell wird außerdem viel Aufwand in die Verbesserung der Dokumentation und das Erstellen von Tutorials investiert. Bisher kryptische Fehlermeldungen durch das Aufsetzen auf Gradle wurden um konkrete Hilfestellungen ergänzt, sodass die Ursachenforschung bei Problemen nun leichter vonstattengeht.
Es ist außerdem leicht, lokal bestehende Skripte anzupassen oder auch neue Aufgaben zu implementieren. Vorkenntnisse in der Programmiersprache Groovy sind dabei allerdings von Vorteil. Hat man einen neuen Im- oder Export implementiert, kann man diesen natürlich auch dem docToolchain-Projekt beisteuern. Bei Fragen steht die stets sehr freundliche Community kompetent und zeitnah zur Verfügung.