Falk Sippach
05.01.2025
Bei Documentation as Code werden leichtgewichtige Auszeichnungssprachen verwendet. Die Auswahl ist groß. Markdown ist derzeit am weitesten verbreitet, aber AsciiDoc bringt wichtige Funktionen out of the box mit. Wir diskutieren, welche Sprache besser für die Dokumentation von Softwarearchitektur geeignet ist.
Mit der Nutzung leichtgewichtiger Textformate können wir unsere Dokumentation direkt im Git-Repository erstellen und versionieren – ganz nah am Sourcecode. So lassen sich verschiedene Versionen problemlos vergleichen und bei Bedarf ältere Stände wiederherstellen. Der Einsatz verteilter Versionskontrollsysteme wie Git ermöglicht es uns, auch offline, etwa im Zug oder in einem Funkloch, an der Dokumentation zu arbeiten. Über Pull-Requests und begleitende Review-Prozesse können wir zudem gemeinsam mit Kollegen an den Inhalten feilen, was die Zusammenarbeit enorm verbessert. Im Vergleich zu klassischen Wikis, die primär auf Online-Kollaboration setzen, bietet dieser Ansatz also den Vorteil der Offline-Fähigkeit. Während Tools wie MS Word oder Google Docs ebenfalls kollaborative Funktionen bieten, schätzen viele Entwickler besonders die Möglichkeit, Dokumentation ohne Kontextwechsel direkt in ihrer gewohnten Entwicklungsumgebung oder ihrem Texteditor zu bearbeiten – ganz so, wie sie es auch mit dem Code tun.
Zusätzlich können wir die als Single Source of Truth dienenden Inhalte in Form von Plain-Text leicht in bestehende Build-Prozesse integrieren und so vielfältige Ausgabeformate wie HTML, PDF, Folien oder auch Microsites erzeugen. Diese modularisierten Textbausteine lassen sich zudem flexibel kombinieren, um auf die Bedürfnisse unterschiedlicher Lesergruppen einzugehen. Auch die Integration generierter Inhalte aus Modellen wie UML-Diagrammen, Datenbankschemata oder Quellcode ist problemlos möglich. Exporte aus anderen Dokumentationswerkzeugen wie Excel, Enterprise Architect oder sogar aus der Git-Historie und Jira-Tickets sorgen dafür, dass unsere Dokumentation stets aktuell bleibt und redundanzfrei erweitert werden kann.
Wie so oft führen mehrere Wege zum Ziel. Im Bereich der leichtgewichtigen Markupsprachen hat sich derzeit Markdown als klarer Marktführer etabliert. Nahezu alle webbasierten, sourcecodenahen Tools wie Code-Repositories (GitHub, GitLab, …) und viele Wikis bieten Unterstützung für dieses Format bereits standardmäßig an.
AsciiDoc ist zwar etwas älter als Markdown, konnte sich jedoch anfangs nicht so stark durchsetzen. Erst mit der Neuimplementierung als Asciidoctor im Jahr 2013, zunächst in Ruby und später auch als Portierungen in Java und JavaScript, gewann AsciiDoc zunehmend an Popularität und ist allmählich zu einer ernstzunehmenden Alternative zu Markdown herangewachsen. Seit 2020 wird unter der Haube der Eclipse Foundation auch an einer Standardisierung gearbeitet.
| Kategorie | Markdown | AsciiDoc |
|---|---|---|
| Erfinder/Autor | John Gruber (in Zusammenarbeit mit Aaron Swartz) | Stuart Rackham |
| Veröffentlichungsjahr | 2004 | 2002 |
| Lizenztyp | Open Source, verschiedene Implementierungen (häufig MIT oder BSD) | Open Source, GPLv2 (AsciiDoc), MIT (AsciiDoctor) |
| Hauptzweck | Einfaches Erstellen von Webtexten und Dokumentation | Umfangreiche technische Dokumentation, z. B. für Softwareprojekte |
| Syntax-Komplexität | Sehr einfach, gut geeignet für Einsteiger | Etwas komplexer als Markdown, jedoch mächtig und flexibel |
| Erweiterbarkeit | Begrenzte Unterstützung, Erweiterungen meist durch spezifische Parser | Hochgradig erweiterbar mit Makros und benutzerdefinierten Stilen |
| Tool-Unterstützung | Breite Unterstützung in Editoren und Plattformen (z. B. GitHub, VS Code) | Gut unterstützt durch Editoren wie Asciidoctor, GitHub, und IDEs |
| Beliebtheit | Sehr verbreitet, speziell in Webprojekten und Dokumentation | Besonders in der Software- und technischen Dokumentation beliebt |
| Standardisierung | CommonMark als Standard, auch GitHub Flavored Markdown (GFM) | Asciidoctor als De-facto-Standard, Standardisierung bei Eclipse Foundation in Arbeit |
| Besondere Features | Leichte Syntax, schnell erlernbar, viele Optionen durch Varianten | Unterstützung für Modularisierung von Dokumenten, Diagramme, Tabellen, Querverweise und CSS-ähnliche Stile |
Markdown ist der De-facto-Standard, der in zahlreichen Tools verfügbar ist, einfach zu erlernen und bei Techniker:innen besonders beliebt für die Dokumentation.
| 👍 | 👎 |
|---|---|
| 80 % Lösung für einfache Auszeichnungen | für anspruchsvollere Dokumentation fehlen wichtige Konzepte wie Tabellen, Includes, TOC, Admonitions, Attribute/Variablen, Anchor, Fußnoten, Syntax Highlighting, … |
| sehr weit verbreitet, große Toolauswahl | die fehlenden Konzepte werden von unzähligen Erweiterungen sehr unterschiedlich und nicht kompatibel angeboten (es gibt eine Vielzahl von Markdown Dialekten) |
| standardmässig überschaubares, aber für einfache Text ausreichendes Feature-Set | je nach Toolchain werden ggf. nicht alle Dialekte unterstützt und die Portierbarkeit von Auszeichnung zw. den Dialekten ist erschwert. |
Das Feature-Set umfasst:
<hr/>)Dagegen fehlen interessante Funktionen (oder werden nur über Dialekte in unterschiedlicher Art und Weise unterstützt):
AsciiDoc klingt vom Namen zwar ziemlich altbacken und sollte vielleicht besser in UnicodeDoc, UTF8Doc oder so ähnlich umbenannt werden. Aber davon abgesehen bringt es schon einige mächtige und interessante Funktionen mit sich.
| 👍 | 👎 |
|---|---|
| zu Markdown kompatible Obermenge, erleichtert den Umstieg | geringere Verbreitung und weniger Toolunterstützung |
| für anspruchsvolle technische Dokumentation entwickelt | |
| leistungsfähige Syntax mit mächtigen Prozessor AsciiDoctor (in Ruby implementiert) | |
| durch JRuby auch auf der Java Plattform und mit Opal im JavaScript-Umfeld nutzbar | |
| sehr vitales Ökosystem (viele Plugins z. B. für Diagrams-as-Code mit PlantUML) | |
| gute Editoren und Preview-Werkzeuge | |
| einfach und flexibel in gängige Build-Prozess-Werkzeuge integrierbar | |
| Standardisierung von AsciiDoc bei der Eclipse Foundation in Arbeit |
Die besonderen Features von AsciiDoc sind:
Welches Tool ist das richtige? Wie so oft kommt es natürlich darauf an. Eine universelle Lösung gibt es nicht. AsciiDoc hat besonders in der technischen Dokumentation die Nase vorn. Allerdings ist Markdown dank seines einfachen Einstiegs, der hohen Verbreitung und der umfassenden Toolunterstützung oft die praktischere Wahl. Für einfache Dokumente wie README.md-Dateien in Git-Repositories reicht Markdown in der Regel aus. Doch bei komplexeren Anforderungen stößt man schnell an Grenzen, die entweder den Verzicht auf erweiterte Formatierungen oder die Nutzung eines spezifischen Markdown-Dialekts erfordern, was die Portabilität erschwert.
Für anspruchsvollere Projekte, wie die Dokumentation einer Softwarearchitektur, empfiehlt es sich, direkt auf das leistungsfähigere AsciiDoc zu setzen. Zwar erfordert es eine spezialisierte Werkzeugkette. Doch ist diese einmal eingerichtet, gestaltet sich die Dokumentation langfristig stressfreier. Zudem schreitet der Standardisierungsprozess voran, was eine breitere Akzeptanz und Nutzung in der Zukunft erwarten lässt.
| Kriterium | AsciiDoc | Markdown |
|---|---|---|
| Lernkurve | Steiler, komplexere Syntax | Einfach, schnell erlernbar |
| Funktionsumfang | Sehr umfangreich (z. B. komplexe Dokumente, Diagramme, Metadaten) | Begrenzt, primär für einfache bis mittlere Dokumente geeignet |
| Tool-Unterstützung | Weniger weit verbreitet, Abhängigkeit von Asciidoctor | Sehr weit verbreitet, native Unterstützung in vielen Tools |
| Flexibilität | Hoch (z. B. Attribute, Erweiterungen) | Eingeschränkt, oft auf Basisfunktionen beschränkt |
| Kompatibilität | Nicht überall nativ unterstützt | Universell unterstützt (z. B. GitHub, CI/CD-Tools) |
| Eignung für Einsteiger | Weniger geeignet, umfangreichere Dokumentationen benötigen Konfiguration | Sehr geeignet, einfacher Start |
| Komplexe Strukturen | Ideal für große, strukturierte Dokumentationen | Schwächen bei komplexen Hierarchien und Verknüpfungen |
| Performance | Langsamere Generierung bei großen Projekten | Schneller, besonders bei einfachen Projekten |
| Anwendungsbereich | Ideal für technische Dokumentationen und anspruchsvolle Anforderungen | Perfekt für schnelle, einfache Dokumentationen |
| Standardisierung | Einheitlicher und klar definierter Syntax | Unterschiedliche Dialekte führen zu Inkonsistenzen |
| Community | Kleiner, aber fokussiert | Groß, mit vielen Ressourcen und Tutorials |
Die Wahl der Markupsprache hängt tatsächlich auch vom jeweiligen Ökosystem ab. Je nach Programmiersprache werden unterschiedliche Formate besser unterstützt. AsciiDoc ist zum Beispiel im Java-Umfeld weit verbreitet, während in der Python-Welt reStructuredText als leistungsfähiges Werkzeug gilt. Allerdings erfordert reStructuredText eine intensivere Einarbeitung. Das kann ein spannendes Thema für einen weiteren Blog-Post sein.