Falk Sippach
01.09.2022
Das Opensource Projekt docToolchain besteht aus einer Sammlung von Skripten, die das Erstellen und Pflegen von technischer Dokumentation erleichtern.
Die Dokumentation Eurer Softwarearchitektur ist wichtig, wird aber mitunter vernachlässigt. Hier setzt “Documentation as Code” an - Entwickler bzw. mit-codende Architekten sollen (wieder) mehr Freude an dieser Tätigkeit haben und sie als weniger lästig ansehen. Eine aktuelle und damit bessere Dokumentation sind erklärtes Ziel. Bei diesem Ansatz wird Dokumenation wie Sourcecode behandelt:
Um all diese Punkte umzusetzen, gibt es bereits verschiedene Tools sowie Erweiterungen in bestehende Buildmanagement-Werkzeuge. Mit etwas Aufwand könnt ihr Euch eure individuelle Toolchain zusammenstellen.
Aber warum das Rad neu erfinden? docToolchain kommt als einsatzbereite, vorkonfigurierte Menge von Skripten, welche die Erzeugung und Wartung von technischer Dokumentation zum Kinderspiel machen. Zudem kann docToolchain sehr einfach an eure jeweiligen Bedürfnisse angepasst werden.
Das Projekt startete 2015 mit einem Groovy-Skript, welches AsciiDoc-Inhalte nach Confluence exportieren konnte. Daraus ist mittlerweile eine große Sammlung von Gradle Plugins und Tasks entstanden. Während die Bedienung in Version 1.x noch direkt über das Build-Tool Gradle erfolgte, wird die Integration von docToolchain mit Version 2.x (seit September 2021) hinter einem für alle gängigen Betriebssysteme verfügbaren Skript (dtcw) versteckt, was Installation und Bedienung stark vereinfachen.
Auf der Webseite gibt es einige Tutorials zur initialen Einrichtung und zur grundlegenden Verwendung. Je nach Betriebssystem muss ein Shell-Skript (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 könnt ihr direkt im Root-Verzeichnis des Dokumentationsprojekts ablegen und dort aufrufen. Bei der ersten Ausführung werden einige Voraussetzungen geprüft und ggf. Teile nachinstalliert (z. B. Gradle und docToolchain selbst). Voraussetzung ist, dass Java (aktuell JDK 11 empfohlen) vorher installiert wurde. Ist auf dem Rechner der Docker-Daemon vorhanden, 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.
Die wichtigsten Befehle, um mit docToolchain ein neues Dokumentationsprojekt zu starten, lauten:
| 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 |
Ein mit downloadTemplate initial erzeugtes Projekt sieht folgendermaßen aus:
Im Unterordner src/docs/arc42 befinden sich eine Vielzahl von AsciiDoc-Dateien, je eine für jedes Kapitel des arc42-Dokumentations-Templates. Diese Struktur könnt ihr nach Belieben anpassen und um weitere Dokumente erweitern. DocToolchain verwendet standardmässig das AsciiDoc-Format (mit dem AsciiDoctor-Interpreter), da es im Vergleich zu Markdown bereits viele notwendige Features (Tabellen, Includes, TOC, …) direkt Out-of-the-Box mitbringt. Ihr könnt docToolchain auch mit Markdown-Dokumenten nutzen. 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 (Rendering, Preview, Einbetten von Grafiken, …) nichts im Wege und vermeidet unnötige Kontextwechsel beim Umschalten auf andere WYSIWYG-Tools (Word, Visio, Powerpoint, …).
Die Ausgaben könnt ihr problemlos an Eure Unternehmensvorgaben (Corporate Identity: Logo, Styling, Schriftarten, …) anpassen. Die Ergebnisse landen im Unterordner build und können jederzeit neu erzeugt werden. Ein Build-Server (Jenkins, …) wird 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. Das erspart paralleles Versenden von Dokumenten (Word-Dateien, PDFs, …) per E-Mail. Ein Link auf den Ablageort genügt und die Leser können sich jederzeit die neueste Fassung anschauen oder herunterladen.
Da die Dokumentation bei Docs-as-Code nahe am Quellcode liegt und aus leichtgewichtigen Textdokumenten besteht, lässt sie sich einfach in den Entwicklungsalltag integrieren. Beugt unnötiger Redundanz vor und generiert z.B. aus vorhandenen Informationen (Datenbankmodell, Quellcode, UML-Diagramme, …) direkt Teile der Dokumentation und haltet sie aktuell. So lässt sich aus den AsciiDoc-Dateien sehr einfach und komfortabel Sourcecode referenzieren. Änderungen am Quellcode werden direkt bei der nächsten Erzeugung der Dokumentation übernommen.
DocToolchain bringt viele vordefinierte Eingabe-Schnittstellen bereits mit. So könnt ihr beispielsweise Inhalte aus Excel-Tabellen als CSV oder sogar direkt als AsciiDoc exportieren, um sie dann als Imort in die bestehende Dokumente zu integrieren. Ein Anwendungfall könnte sein, dass der Fachbereich Abnahmekriterien für User-Stories in einer Excel-Tabelle pflegt und diese auch regelmässig aktualisiert. Diese Inhalte können sogar mit Formatierungen (Spaltenbreiten, Col- und Row-Span, Farben, …) übernommen werden. Der zugehörige Task heißt exportExcel.
Auf effiziente Art und Weise könnt ihr vorhandene Visio- oder Powerpoint-Inhalte als Grafiken exportieren und dann aus den Ascii-Dokumenten heraus referenzieren. Auch hier wird bei Änderungen an den Originaldateien ein Update generiert - ohne zusätzlichen manuellen Aufwand.
Exporte von Informationen aus dem UML-Modellierungswerkzeug Enterprise Architect sind ebenso problemlos möglich. Ihr könnt sowohl die verschiedenen Diagramme als Bild-Dateien, als auch die Notizen als Texte extrahieren und dann in die bestehenden AsciiDoc-Dateien einbetten. Somit lassen sich z. B. vorhandenen Baustein- (Komponentendiagramme, …) oder Laufzeitsichten (Sequenzdiagramme, …) einbinden und um eine tabellarische Beschreibung der einzelnen Elemente ergänzen. Auch hier gilt: Ändert sich etwas am Original, wird durch die erneute Erstellung der Dokumentations-Artefakte der Stand automatisch aktualisiert.
Weitere Eingabequellen sind:
In der nachfolgenden Übersicht sind auf der linken Seite die verschiedenen Inputformate aufgeführt.
Das Schaubild zeigt zudem die verschiedenen Optionen, welche docToolchain für die Erstellung der Dokumentation bereithält. Neben den Klassikern (HTML, PDF) lassen sich über das DocBook-Format auch Word-Dokumente bwz. EPub-Dateien und sogar mit Reveal.js-gebaute Präsentationen erstellen. Absolutes Killerfeature bei den Ausgabeformaten ist der publishToConfluence-Task. Confluence ist aus kaum einer IT-Abteilung wegzudenken - das kommerzielle Wiki von Atlassian hat sich zum Defacto-Standard entwickelt. Häufig wird es auch für die Erstellung und Pflege der technischen Dokumentation eingesetzt. Vorteil ist, dass man auch mit nicht-technikaffinen Kollegen (z. B. aus dem Fachbereich) an Confluence-Seiten gemeinsam arbeiten kann. Obwohl gute Strukturierungsmöglicheiten und eine gut funktionierende Suche vorhanden ist, findet man häufig wichtige Informationen kaum wieder. Passend dazu gibt es ein schönes Zitat: “Das Wiki ist der Ort, wo die Dokumente zum Sterben hingehen.”
Durch publishToConfluence können nun beide Welten zusammengebracht werden. Als Entwickler und Architekten schreibt ihr Eure Dokumentation in leichtgewichtigen Text- und Grafikformaten nach dem Docs-as-Code-Ansatz. Durch den Export nach Confluence stehen die Ergebnisse den anderen Personengruppen über Lesezugriff direkt zur Verfügung. Die Kommentarfunktion des Wiki unterstützt, um bei Review-Prozessen Feedback zu geben. Änderungen im Confluence erfolgen ausschließlich über Kommentare und werden beim nächsten Export wieder überschrieben.
DocToolchain ist in den letzten Jahren eine sehr beliebte Hilfe im Umfeld von Documentation as Code geworden. Während in der Version 1.x die enge Verknüpfung mit dem Build-Management-Tool Gradle noch deutlich war, gibt es mit dem Wrapper nun eine Entkopplung für die Kommandozeile. Künftig soll Gradle ganz aus docToolchain verschwinden. Da es unsichtbar unter der Haube werkelt, spricht auch nichts dagegen, docToolchain mit anderen Tools (z. B. Maven) bzw. in ganz anderen Umgebungen (z. B. außerhalb der Java-Welt) einzusetzen.
Neben dem Wrapper hat sich mit Version 2.x einiges mehr getan. So könnt ihr docToolchain auch in einem vorbereiteten Docker-Container ausführen und spart die Aufwände für eine lokale Installation der notwendigen Abhängigkeiten. Die automatische Installation des arc42-Templates erleichtert Euch zudem den Start eines neuen Dokumentationsprojekts. Und mit jBake wurde ein auf Java-basierender, statischer Seiten-Generator integriert, um Micro-Websites z. B. als Einstieg in einen Architekturüberblick zu erzeugen. Auch hier sind das Design und Layout flexibel auf Eure betrieblichen Anforderungen und eigenen Wünsche anpassbar.
Das Open Source Projekt unter der Leitung von Ralf D. Müller entwickelt sich ständig weiter. An die 50 Committer haben bereits dazu beigetragen. Teile der verfügbaren Export- und Generierungs-Tasks wurden von der Community beigesteuert. Aktuell wird zudem viel Energie in die Verbesserung der Dokumentation und das Erstellen von Tutorials investiert. Kryptische Fehlermeldungen (durch das Aufsetzen auf Gradle) wurden nun um konkrete Hilfestellungen ergänzt, so dass die Ursachenforschung bei Problemen leichter erfolgen kann.
Lokal bestehende Skripte könnt ihr nun leichter anpassen oder auch neue Aufgaben implementieren. Vorkenntnisse in der Programmiersprache Groovy sind dabei von Vorteil. Habt ihr einen neuen Im- oder Export implementiert, könnt ihr diesen auch dem docToolchain-Projekt beisteuern. Bei Fragen steht Euch die stets sehr freundliche Community kompetent und zeitnah zur Verfügung.
Training zu Documentation-as-Code bei der socreatory