Softwaredokumentation ist heute mehr als eine Pflichtaufgabe. Sie ist Teil des Entwicklungsprozesses und muss genauso agil, versionierbar und automatisierbar sein wie der Quellcode selbst. Klassische Office-Dokumente oder proprietäre Wikis stoßen dabei schnell an ihre Grenzen. Änderungen sind schwer nachzuvollziehen, Zusammenarbeit ist umständlich und eine Integration in CI/CD Pipelines ist kaum möglich.
AsciiDoc und Kroki greifen genau diese Punkte auf. Beide Werkzeuge stehen für den Ansatz Docs-as-Code, bei dem Dokumentation wie Quellcode behandelt wird. AsciiDoc bietet eine ausdrucksstarke textbasierte Sprache für technische Dokumentation, die sich in Git verwalten und automatisiert verarbeiten lässt. Kroki ergänzt dies um die Möglichkeit, Diagramme direkt im Dokument einzubetten und automatisch zu rendern. So können Entwicklerinnen und Entwickler Diagramme nutzen, ohne zusätzliche Tools installieren zu müssen.
Die Kombination ist zwar nicht neu, sie schafft aber einen klaren Mehrwert: Inhalte und Visualisierungen bleiben im gleichen Repository, Änderungen sind jederzeit nachvollziehbar und Ausgabeformate von HTML bis PDF lassen sich automatisiert erzeugen. Dokumentation wird dadurch zu einem festen und reproduzierbaren Bestandteil der Softwareentwicklung. Sie bleibt transparent, flexibel und unabhängig von proprietären Plattformen.
Was ist AsciiDoc
AsciiDoc ist eine Auszeichnungssprache, die speziell für technische Dokumentationen entwickelt wurde. Im Gegensatz zu klassischen Office-Dokumenten oder WYSIWYG-Editoren trennt AsciiDoc konsequent Inhalt und Darstellung. Der Text wird in einer leicht lesbaren Syntax geschrieben und kann anschließend in verschiedene Ausgabeformate wie HTML, PDF oder DocBook konvertiert werden.
Warum AsciiDoc?
AsciiDoc verfolgt denselben Gedanken wie Markdown, bietet aber deutlich mehr Funktionen. Es unterstützt Tabellen, Querverweise, Variablen, Includes, Fußnoten, Inhaltsverzeichnisse und Erweiterungen wie das Einbinden von Diagrammen. Damit eignet es sich nicht nur für einfache README-Dateien, sondern auch für umfangreiche Handbücher, Spezifikationen oder Schulungsunterlagen.
Vorteile in der Softwareentwicklung
- Versionskontrolle: Da AsciiDoc reiner Text ist, lässt es sich problemlos in Git oder anderen Versionsverwaltungssystemen nutzen. Änderungen sind transparent nachvollziehbar, Unterschiede zwischen Versionen klar erkennbar.
- Automatisierung: AsciiDoc-Dokumente können Teil einer Build-Pipeline sein. Dokumentationen lassen sich gemeinsam mit der Software aus dem gleichen Repository erzeugen. Damit wird Dokumentation ein fester Bestandteil des Entwicklungsprozesses und nicht ein nachgelagerter Schritt.
- Wiederverwendbarkeit: Inhalte können modular strukturiert und mit Include-Anweisungen wiederverwendet werden. Das spart Zeit und vermeidet Redundanzen, zum Beispiel bei sich wiederholenden Abschnitten wie Lizenztexten oder Standard-Hinweisen.
- Integration von Diagrammen: In Kombination mit Asciidoctor-Diagram und Kroki lassen sich Diagramme direkt in den Text einbetten. Der Quelltext und die Visualisierung bleiben zusammen im Repository, was die Wartung erheblich vereinfacht.
- Unabhängigkeit von proprietären Formaten: AsciiDoc ist offen und standardisiert. Es gibt keine Abhängigkeit zu bestimmten Herstellern oder Programmen. Das macht die Dokumentation zukunftssicher und portabel.
AsciiDoc ist eine robuste Grundlage für technische Dokumentationen in Softwareprojekten. Es vereint die Einfachheit von Textdateien mit der Ausdrucksstärke einer vollwertigen Auszeichnungssprache. Besonders im Umfeld von Softwareentwicklung, Continuous Integration und DevOps-Prozessen bringt es klare Vorteile: Dokumentation wird versionierbar, automatisierbar und eng mit dem Quellcode verknüpft.
Was ist Kroki
Kroki ist ein Open-Source-Dienst, der aus textuellen Beschreibungen automatisch Diagramme erzeugt. Statt einzelne Programme wie PlantUML, Graphviz oder Mermaid lokal zu installieren, stellt Kroki eine einheitliche HTTP-Schnittstelle bereit. Man übergibt eine Textdatei an den Dienst und erhält eine Grafik im gewünschten Format zurück, zum Beispiel als SVG oder PNG.
Welche Diagrammsprachen unterstützt werden
Kroki bindet eine große Auswahl an Engines ein. Dazu gehören UML-Diagramme über PlantUML, Architekturdiagramme mit C4 oder Prozessdarstellungen in BPMN, Netzwerke mit Graphviz und viele mehr. Das macht es möglich, in einer Dokumentation unterschiedliche Notationen zu kombinieren, ohne dass der Leser oder Autor zusätzliche Software installieren muss.
Vorteile im Entwicklungsalltag
Der größte Vorteil liegt in der Vereinheitlichung. Statt verschiedene Tools und Installationen pflegen zu müssen, reicht ein einziger Kroki-Server. Das spart Zeit bei der Einrichtung und reduziert Abhängigkeiten.
Ein weiterer Aspekt ist die Automatisierung. Da Kroki über eine API angesprochen wird, kann es problemlos in CI/CD-Pipelines eingebunden werden. Dokumentationen lassen sich damit automatisch erzeugen, inklusive der dazugehörigen Diagramme. Änderungen im Quelltext oder in den Diagrammbeschreibungen werden direkt in den generierten Dokumenten sichtbar, ohne dass jemand manuell eine Grafik neu exportieren muss.
Auch in Teams bringt Kroki Vorteile. Alle Beteiligten greifen auf denselben Dienst zu und arbeiten mit den gleichen Versionen der Engines. Das verhindert Unterschiede zwischen lokalen Installationen und sorgt für reproduzierbare Ergebnisse.
Verbindung zu AsciiDoc
Besonders interessant wird Kroki in Verbindung mit AsciiDoc. AsciiDoc erlaubt es, Diagrammcode direkt in die Dokumentation einzubetten. Normalerweise wäre dafür ein lokales Backend wie PlantUML oder Mermaid erforderlich. Mit Kroki reicht jedoch ein einfacher Konfigurationsparameter.
Installation
AsciiDoc
Um mit AsciiDoc arbeiten zu können, brauchst du eine Rendering Engine. Die am weitesten verbreitete ist Asciidoctor. Sie wandelt AsciiDoc-Dateien in HTML oder PDF um. Für die Verarbeitung von Diagrammen kommt zusätzlich das Plugin Asciidoctor Diagram zum Einsatz.
Asciidoctor ist in Ruby geschrieben. Deshalb muss Ruby auf dem System installiert sein. Unter Windows 11 bietet sich die Installation über das RubyInstaller.
Sobald Ruby eingerichtet ist, installierst du die benötigten Pakete mit dem Ruby Paketmanager gem.
Um Diagramme mit Kroki direkt in AsciiDoc zu rendern, empfiehlt sich die Verwendung der Erweiterung asciidoctor-kroki. Während asciidoctor-diagram versucht, lokale Tools wie PlantUML oder Graphviz aufzurufen, bindet asciidoctor-kroki den Kroki-Server direkt über HTTP ein.
Zum Testen erstellen wir eine Testdatei helloworld.adoc mit dem folgenden Inhalt:
Mit folgendem Befehl wandelst du die Datei in HTML um:
Visual Studio Code bietet mit der Erweiterung AsciiDoc by Asciidoctor die Möglichkeit, AsciiDoc-Dateien direkt im Editor als Vorschau darzustellen. Während man im linken Fenster den AsciiDoc-Quelltext schreibt, zeigt die Erweiterung im rechten Fenster das daraus gerenderte HTML an. Auf diese Weise lassen sich Änderungen am Dokument sofort überprüfen, ohne dass man den Text vorher manuell in HTML umwandeln muss.
Kroki
Unter Windows lässt sich Kroki sehr einfach mit Docker Desktop betreiben. Docker übernimmt dabei die komplette Installation und Verwaltung der Anwendung. Es ist keine zusätzliche Konfiguration notwendig.
Damit wird Kroki automatisch aus dem Docker Hub heruntergeladen und im Hintergrund gestartet. Über den Browser ist der Dienst anschließend unter http://localhost:8000 erreichbar. Auf diese Weise steht sofort ein funktionsfähiger Kroki-Server bereit, der für die Erzeugung von Diagrammen genutzt werden kann.
Der gezeigte Text ist ein vollständiges AsciiDoc-Dokument, das ein Diagramm mit Kroki rendert. In der ersten Zeile steht der Dokumenttitel. Mit der Zeile :kroki-server-url: http://localhost:8000 wird festgelegt, dass Kroki als Server für die Diagrammerzeugung verwendet wird. Der Block [plantuml, format=svg] kündigt ein PlantUML-Diagramm an, das als SVG ausgegeben werden soll. Zwischen den Linien —- befindet sich der eigentliche PlantUML-Code. Dieser beschreibt ein einfaches Sequenzdiagramm, in dem Alice eine Nachricht an Bob schickt und Bob mit einer Antwort reagiert. Beim Rendern wird dieser Code automatisch an Kroki übergeben und als Grafik in das fertige Dokument eingefügt.
Dieser Befehl wandelt eine AsciiDoc-Datei in HTML um und rendert enthaltene Diagramme über den Kroki-Server.
Beispiel Dokumente
Hier ist ein Beispiel zu sehen, das die wichtigsten Funktionen von AsciiDoc demonstriert. Es ist nicht vollständig, sondern soll nur einen Eindruck geben, wie sich verschiedene Formatierungen nutzen lassen.
Über den Autor
