Wir kennen das alle, diese gewisse Abscheu des Entwicklungsteams in puncto Dokumentation. Der Horror vor ungeeigneten Werkzeugen, fehlender Versionierung und binären Datenformaten. Wir schaffen Abhilfe. Schritt für Schritt führen wir Sie in dieser Kolumne an das Konzept Docs as Code heran, bei dem Sie Ihre technische Dokumentation – insbesondere Architekturdokumentation – genauso behandeln wie Ihren Code: schreiben, bauen, testen, committen, mergen. Gut, oder?
Traditionell nutzen Unternehmen primär Textverarbeitung als Grundlage technischer Dokumentation. Die entsprechenden Produkte – meistens Microsoft Word – sind überall vorhanden und das Management ist damit zufrieden. Entwicklungsteams sehen das ganz anders. Wir müssen mit Tools, die für Briefeschreiben und Single-User-Betrieb ausgelegt sind, komplexe, volatile und teilweise grafiklastige Dokumentationen erstellen und pflegen, über lange Zeit aktuell halten sowie Versionen und Releases unterstützen. Aua!
Andere Ansätze, wie Javadoc, erfüllen nur einige spezielle Anforderungen an Dokumentation (Klassendokumentation) oder bieten nur einen eingeschränkten Funktionsumfang. Dann wäre da noch das bei Bloggern beliebte Markdown. Das ist einfach und fast universell einsetzbar. Es scheitert aber bereits an längeren Tabellen oder größeren Dokumenten. Denn dafür wurde es auch nicht entwickelt. Wer dennoch Markdown bevorzugt, findet nützliche Tipps in einer älteren Ausgabe des Java Magazins. AsciiDoc füllt diese Lücke (Interessant ist ebenfalls der Wikipedia-Eintrag). Dieses rein textuelle Format besticht einerseits durch eine einfache Syntax, die recht ähnlich zu Markdown ist. Es ermöglicht auf der anderen Seite aber vielseitige Formatierungen ähnlich wie WYSIWYG-Textverarbeitungen. Das Beste: Sie behandeln AsciiDoc genau wie Quellcode, aber dazu später mehr.
Hello, World
Wenn es wie Quellcode aussieht, sollten Sie es auch wie eine Programmiersprache kennenlernen, nämlich mit einem Hello-World-Beispiel. Listing 1 zeigt ein einfaches AsciiDoc-Dokument mit ein paar extra Features. Überschriften beginnen mit einem oder mehreren =, je nach Schachtelungstiefe. Mit * am Zeilenanfang beginnt eine Aufzählung, und der Rest von hello.adoc erklärt sich von selbst.
Listing 1: hello.adoc
:source-highlighter: coderay
== Ein erstes Asciidoc(ument)
Absätze können
beliebig viele
Zeilenumbrüche
enthalten.
Erst nach einer Leerzeile beginnt ein neuer Absatz.
=== Überschriften
Textformatierungen, Aufzählungen (Listen)
* kennen Sie von Wikis oder Markdown:
* Formate wie *fett*, _kursiv_
* Auch Links sind einfach: http://javamagazin.de[JavaMagazin].
.Code-Highlighting
[source,groovy]
10.times { println "Hello, AsciiDoc!" }
Was ordentlicher Sourcecode sein möchte, gehört natürlich in den Build-Prozess. Wir schlagen Gradle vor, aber mit Maven oder Make oder Buildr geht es natürlich auch. Wir verwenden ein Gradle-Plug-in namens Asciidoctor, um unser hello.adoc aus dem AsciiDoc-Format in etwas optisch Ansprechendes zu verwandeln. Den Unterschied zwischen doc und doctor finden Sie im Textkasten erklärt. Falls Ihnen das zugehörige Listing 2 etwas zu kurz vorkommt, Sie sehen ganz richtig, denn eine einzige Zeile genügt uns momentan.
Listing 2: gradle.build
plugins { id "org.asciidoctor.convert" version "1.5.3" }
Im Hintergrund kapselt das Asciidoctor-Plug-in den in Ruby geschriebenen Standardkonverter für AsciiDoc via JRuby. Aber von diesen Feinheiten im Hintergrund bekommen Sie im Normalfall überhaupt nichts zu sehen.
Wir verwenden übrigens Gradle aufgrund der unserer Meinung nach deutlich besseren Lesbarkeit, der angenehmen Kürze der Build-Files und der großartigen Möglichkeiten, zusätzliche Funktionen im Build zu integrieren. Davon werden wir in den kommenden Folgen dieser Kolumne noch Gebrauch machen.
Legen Sie die Datei build.gradle in ein Projektverzeichnis und unser hello.adoc in das darunterliegende Verzeichnis ./src/docs/asciidoc, können Sie mit gradle asciidoc den Build starten und erhalten als Ausgabe ein sauber formatiertes HTML5-Dokument im Verzeichnis ./build/asciidoc/html5 (Abb. 1). Als Voraussetzung dafür sollten Sie natürlich Gradle installiert haben.
Möchten Sie es Ihren Kollegen noch einfacher machen, dann starten Sie einmal gradle wrapper als Kommando, und Gradle erzeugt im Projekt einen sogenannten Wrapper. Danach braucht Ihr Team noch nicht mal Gradle installiert zu haben, sondern nutzt einfach das Kommando gradlew anstelle von gradle. Der Wrapper installiert beim ersten Aufruf die benötigte Gradle-Version direkt aus dem Netz oder einer anderen Lokation, die man konfiguriert, und arbeitet von da an weiter mit dieser.
AsciiDoc und Asciidoctor
Der Begriff AsciiDoc bezeichnet zwei verschiedene Aspekte. Die Definition einer Auszeichnungssprache, die bereits 2002 entwickelt wurde. Dazu schreibt Stuart Rackham, der Erfinder dieser Syntax: „You write an AsciiDoc document the same way you would write a normal text document. There are no markup tags or weird format notations. AsciiDoc files are designed to be viewed, edited and printed directly or translated to other presentation formats.“ Außerdem bezeichnet es eine Python-basierte Open-Source-Software, um AsciiDoc-Dokumente in andere Formate (HTML, etc.) zu transformieren. Diesen ursprünglichen AsciiDoc-Prozessor hat ebenfalls Stuart Rackham entwickelt. Das System ist stabil, wird allerdings nicht mehr intensiv weiterentwickelt. Dan Allen hat unter dem Namen Asciidoctor eine moderne Implementierung eines AsciiDoc-Prozessors in Ruby entwickelt, die sich leicht in andere Build-Umgebungen integrieren lässt und diverse Erweiterungspunkte für Integrationen bietet, z. B. für Diagramme. In dieser Kolumne verwenden wir Asciidoctor.
Es geht noch (viel) weiter
Dokumente für unterschiedliche Stakeholder aus einem einzigen Repository generieren? Besondere Formatierungen, Glossare, Tabellen und Fußnoten? Umfangreiche Dokumentation modularisieren? Schicke Diagramme und Grafiken integrieren? Bekommen Sie demnächst von uns alles vorgesetzt, in kleinen Portionen, leicht verdaulich. Zu jeder Folge von HHGDAC – aka Kolumne für schmerzfreie Dokumentation – gibt es einen eigenen Branch im zugehörigen GitHub Repository mit Beispielen.
Wir, Ralf und Gernot, möchten das Thema „Technische Dokumentation“ für Sie zu einem angenehmen und einfachen Erlebnis machen. Wir alle haben lange genug unter schlechten Tools gelitten. Jetzt soll es endlich besser werden. Auf Basis von frei verfügbaren Werkzeugen rund um AsciiDoc stellen wir Ihnen eine leistungsfähige, pragmatische und sofort einsetzbare Werkzeugkette vor, die Sie als Grundlage Ihrer eigenen Dokumentation verwenden können. In der nächsten Folge adressieren wir das Thema Modularisierung von Dokumentation und erklären, wie Sie die Dokumentation großer Systeme mithilfe von AsciiDoc in leicht verdauliche Portionen zerlegen können oder auch aus einem einzigen Repository unterschiedliche Dokumente für verschiedene Stakeholder generieren können. Bis dahin: Happy docu-coding!
