24. März 2021
Bei komplexen Softwarelösungen ist eine gute und vor allem aktuelle technische Dokumentation unerlässlich: Sie erleichtert die Kommunikation innerhalb des Projektes, die Nachvollziehbarkeit von Implementierungen und hilft neuen Team-Mitgliedern, sich schnell in der Software zurechtzufinden. Neben dem hohen initialen Aufwand stellt aber gerade die kontinuierliche Pflege der technischen Dokumentation eine große Herausforderung dar – gerade im agilen Ansatz mit kurzen Entwicklungszyklen und sich entsprechend schnell verändernder Software. Idealerweise sollte die Dokumentation daher von den Team-Mitgliedern selbst gepflegt werden können – und zwar im Zuge der eigentlichen Implementierung. Leider sind viele gängigen Dokumentationstools und -editoren ebenso umständlich wie zeitraubend und in der Regel weit entfernt von der täglichen Realität der Entwicklerinnen und Entwickler. Oft scheitert die Pflege der Dokumentation nicht am Willen der Projektbeteiligten, sondern an unnötigen technischen Hürden.
Aus diesem Grund setzt sich zunehmend der Trend zum „Documentation-as-Code“-Ansatz durch.
Das bedeutet, bei der technischen Dokumentation anstelle von Word-Dokumenten, Sharepoints und Wikis auf die gleichen Tools und Methoden zu setzen, die Entwicklerinnen und Entwickler in ihrer tagtäglichen Arbeit ohnehin anwenden: Der Entwicklungsumgebung (IDE) zum Schreiben der Dokumentation, dem GIT-Repository zur Verwaltung und Versionierung und der Buildchain zum Kompilieren der technischen Dokumentation im jeweils gewünschten Ausgabeformat.
An erster Stelle steht dabei die Wahl eines geeigneten Textformats: Grundsätzlich sollte hier ein Plain Text-Format gewählt werden, das sich in der IDE bearbeiten lässt und idealerweise auf die spezifischen Anforderungen der technischen Dokumentation ausgerichtet ist.
In jüngerer Zeit setzt sich dabei das Format Asciidoc durch, weil es eine besonders flexible und ausdrucksstarke, aber gleichzeitig gut lesbare Auszeichnungssprache ist und – im Gegensatz bspw. zum Platzhirschen Markdown – grundsätzlich auf verschiedene sogenannte „Flavours“ verzichtet, also ohne konfligierende Standards auskommt.
Als besonderes Feature sticht bei Asciidoc dabei die include-Funktion hervor, mit der innerhalb eines Textdokuments andere Texte oder Textausschnitte eingebettet werden können. Zum einen lassen sich dadurch bei wiederkehrenden Informationen Redundanzen vermeiden, weil der zugrundeliegende Textbaustein an nur einer Stelle abgelegt und gepflegt werden muss. Und zum anderen bedeutet das auch, dass selbst tatsächlicher Code inkludiert werden kann, vorausgesetzt, er ist an einer für das Asciidoc-Dokument zugänglichen Stelle abgelegt. Mit Asciidoctor steht dabei ein kontinuierlich weiterentwickelter Open-Source-Textprozessor zur Verfügung, mit dem sich die Asciidoc-Dokumente in die unterschiedlichsten Ausgabeformate wie HTML5, PDT, DocBook, etc. konvertieren lassen.
Für viele Entwicklungsumgebungen existieren Plug-Ins für das Highlighten und die Render-Vorschau, so dass sich die Dokumentation dort komfortabel bearbeiten lässt. Die Textdokumente können dann also nicht nur problemlos in der Entwicklungsumgebung geschrieben werden, sondern genau wie der Programmcode selbst an das GIT-Repository übergeben werden.
Möchte man seine Dokumentation als statische Webseite zur Verfügung stellen, sollte man einen Blick auf Antora werfen: Antora ist ein auf Asciidoc basierender Static-Site-Generator, mit dem die Dokumentation als HTML-Webseite generiert werden kann. Die technische Dokumentation ist dann nicht nur korrekt versioniert, sondern die einzelnen Seiten auch automatisch mit den Quelldokumenten im GIT verlinkt. Die Textdokumente können dann dort – wenn gewünscht – im Rohformat von Dritten weiterbearbeitet werden. Weil die gängigsten GITs Asciidoc von Haus aus unterstützten, können sie auch dort in gerenderter Form betrachtet werden.
Integriert man diesen Ansatz in seine Build Chain, kann mit jedem Deployment der Software gleichzeitig auch die technische Dokumentation als statische Webseite generiert und an gewünschter Stelle abgelegt werden. Auf diese Weise wird die technische Dokumentation schnell vom lästigen und oft vernachlässigten Übel zum integralen Bestandteil der agilen Projektarbeit.
Weiterführende Links*:
Haben Sie Fragen zu dem Thema oder sind Sie an einer Unterstützung in diesem Bereich interessiert?
Kontaktieren Sie uns einfach. Wir freuen uns auf Sie!
* Trotz sorgfältiger inhaltlicher Kontrolle übernehmen wir keine Haftung für die Inhalte externer Links.
Für den Inhalt der verlinkten Seiten sind ausschließlich deren Betreiber verantwortlich.
