Dokumentieren ist nicht jedermanns Sache. Neben der Frage: «Was gehört eigentlich in eine Dokumentation?», diskutieren Entwickler immer wieder, mit was für Tools die Dokumentation erstellt sowie aktuell gehalten werden soll und wo man sie Ablegen soll, damit sie auch von allen gefunden wird. Bei der Tools- und Ablage-Fragestellung kann Doc-as-Code die Lösung sein. Doch was versteckt sich hinter diesem Ansatz?
Was ist Doc-as-Code
«Doc-as-Code» oder auch «Documentation-as-Code» bezeichnet den Ansatz, die Dokumentation mit den gleichen Werkzeugen und Prozessen zu erstellen sowie zu verwalten, die auch zur Entwicklung von Software verwendet wird. Die Dokumentation wird dabei in einem textbasierten Format wie zum Beispiel Markdown oder Asciidoc geschrieben und mit einem Versionskontrollsystem wie Git verwaltet und gespeichert. Der Softwareentwickler kann für diese Tätigkeit seinen favorisierten Code-Editor nutzen, um die Dokumentation zu erweitern und zu pflegen.
In Kombination mit CI/CD-Pipelines kann die Dokumentation automatisch validiert und in verschiedene Formate, wie zum Beispiel PDF, konvertiert werden. Das führt dazu, dass die Dokumentation nicht länger ein Dokument ist, das Vergessen wird und irgendwo gespeichert herumliegt, sondern sie wird Teil des Entwicklungsprozesses.
Formate und Werkzeuge
Die bereits oben erwähnten Formate Markdown und Asciidoc haben sich als leichtgewichtige Textformate etabliert. Diverse Anbieter wie Github oder Wikis unterstützen das automatische Rendern in der Webansicht von Haus aus. Die Syntax der beiden Formate ist einfach, trotzdem aber sehr mächtig. Für das technische Schreiben bringt Asciidoc wichtige Elemente wie ToC, Tabellen oder Imports direkt mit. Für Markdown sind diese Elemente ebenfalls verfügbar, jedoch nur über diverse Erweiterungen oder spezifische Dialekte.
Die Dokumentation wird als Textdateien im Filesystem gespeichert und letztendlich mit einem Versionskontrollsystem wie Git versioniert und verwaltet. Um die Wart- und Wiederverwendbarkeit zu steigern, lassen sich die Textdateien in einzelne Dateien aufteilen. Die «modularisierten» Textdateien können dann in andere Dokumente inkludieren.
Zum Erstellen und Pflegen der Dokumentation reicht grundsätzlich ein einfacher Texteditor. In der heutigen Zeit arbeiten die meisten Entwickler sowieso mit einer integrierten Entwicklungsumgebung (IDE) und da bietet es sich an, die Dokumentation direkt dort zu verwalten.
Viele moderne IDEs bieten zu dem Plug-Ins mit nützlichen Funktionalitäten an, wie Syntax-Highlighting und Autovervollständigung, Interpreter für das Rendern von Textformaten als Preview, das Rendern von Diagrammformaten wie PlantUML oder eingebettete Grafikeditoren.
Für das Übersetzen der Textformate in ein Ausgabeformat wie PDF oder HTML gibt es diverse Plug-Ins für die unterschiedlichen Build-Systeme. Das Opensource-Tool docToolchain bringt darauf aufbauend viele zusätzliche Import- und Export-Schnittstellen mit. Zum Beispiel lassen sich damit existierende Inhalte aus PowerPoint, Excel, Enterprise Architect usw. in die Dokumentation einbinden. Die docToolchain bietet auch die Möglichkeit, die fertige Dokumentation in Confluence zu exportieren, um eine breite Leserschaft zu erreichen. Zudem kann man Vorlagen verwalten, um firmenweit ein einheitliches Layout zu pflegen oder lässt sich die Dokumentationsstruktur nach arc42 gliedern.
Fazit
Der Ansatz «Doc-as-Code» macht die Arbeit für Entwickler effizienter und bequemer. Er bringt die bekannten Vorgehensweisen der Softwareentwicklung in die Welt der technischen Dokumentation.
Durch die Versionskontrolle wird die Kollaboration verbessert und alle Änderungen sind nachvollziehbar. Die Entwickler können die ihnen bekannte Tools und Prozesse nutzen. Automatisierung mittels CI/CD erhöht die Konsistenz und Qualität durch frühzeitiges Erkennen von fehlerhafter Rechtschreibung, inkorrekte Links oder falscher Formatierung. Das Risiko von veralteter Dokumentation wird minimiert, da sich Code und Dokumentation im selben Repository befinden. Und es eignet sich für kleine als auch für grosse Projekte. Dank textbasierter Formate und automatisierter Prozesse ist eine Skalierung einfach möglich.
