Docs like Code

Warum Dokumentation ins Repository, und nicht in Word gehört

Ich gebe es ja zu: Dokumentation schreiben gehört nicht zu meinen Lieblingsaufgaben als Entwickler. Schon gar nicht, wenn es in einem mäßig gepflegten Wiki, Confluence, oder (am schlimmsten) Word passiert. Hier treffen einfach zwei Welten aufeinander: wir Entwickler lieben unseren mühevoll getunten Editor, alles ist ein Textfile, und wenn es nicht in git ist, dann existiert es für uns nicht. Unsere Arbeit einfach in irgendein Tool, oder gar auf eine Website zu tippen, passt da so gar nicht zum gewohnten Workflow. Vielleicht hapert es auch deshalb in vielen Projekten mit der Doku?

Dabei gibt es durchaus Positivbeispiele: fast jedes Repository auf Github hat ein README, was das Projekt und seine Verwendung in groben Zügen erklärt. Das Dokument ist als einfache Textdatei zusammen mit dem Code eingecheckt und meist in Markdown formatiert. Es ist so einfach, so eine Datei in ein Repository aufzunehmen, dass es fast alle Projekte tun. Kann das vielleicht auch im Großen funktionieren?

Docs like Code

Warum also nicht Dokumentation behandeln wie Source-Code? Die Kernidee dabei ist es, uns Entwicklern die Arbeit durch weniger Medienbrüche und Automatisierung leichter zu machen. Wir wollen:

• Dokumentation in der IDE/dem Editor statt auf Webseiten oder in Word schreiben
• Versionskontrolle wie git zum Speichern, Versionieren und Verteilen verwenden. Schluss mit Emailketten und Doku_v1.2_GT_Review_final.docx!
• In textbasierten Formaten (Markdown, Asciidoc) arbeiten, damit Änderungen leicht zu reviewen und nachzuvollziehen sind, ohne dabei auf Layouting (Überschriften, Bilder, Tabellen, Listings) verzichten zu müssen.
• Inhalte von der Präsentation trennen: Doku wird einmal geschrieben und in unterschiedliche Layouts/Formate (HTML, PDF, epub…) kompiliert.
• Continuous-Integration-Tools zum Bauen und Deployen der Dokumentation verwenden, damit wir Änderungen schnell einpflegen können und stets überall die neuste Version abgelegt ist.

Die schnellste Variante ist, einfach einen docs Ordner neben den Quellcode im Repository anzulegen und mit Markdown-Dateien loszulegen. Die Syntax ist so einfach, dass auch Nicht-Entwickler schnell damit klarkommen. Es gibt Unmengen von Tools mit Vorschaufunktion, die beim Schreiben helfen. Struktur lässt sich über Links zwischen den Dokumenten bringen.

Die Idee: links der Quelltext, rechts die gerenderte Dokumentation

Asciidoctor

Für besonders umfangreiche Dokumentation, oder wenn das Layout des Dokuments komplexer wird (z.B. Fußnoten, Beschriften von Abbildungen, nummerierte Kapitel, Verzeichnisse), stößt Markdown irgendwann an seine Grenzen. Auch gibt es viele unterschiedliche Stilrichtungen mit eigener Syntax, was es schwierig macht, mal eben zu googlen wie z.B. eine Tabelle erstellt wird. Hier kann Asciidoctor punkten: Die Syntax ist zwar ein bisschen komplexer, lässt aber kaum einen Featurewunsch offen. Den Einstieg erleichtert die sehr gute und umfangreiche Doku.

Das Tool kann neben HTML auch PDF, oder Docbook generieren. Über Themes bekommen die Dokumente einen zur Corporate-Identity passenden Look.

Unter technischen Autoren erfreut sich Asciidoctor steigender Beliebtheit — was vermutlich auch daran liegt, dass das bekannte arc42-Template in dieser Syntax herausgegeben wird.

Plugins

Mit Docs-as-Code wird es auch möglich, langweilige Aufgaben zu automatisieren. Für Asciidoc gibt es dafür eine ganze Reihe an Plugins. Hier ein paar Beispiele:

• wer auch Diagramme lieber im Text-Editor statt im UML-Modeler zeichnet, der wird mit Asciidoctor-Diagram sicher glücklich: das Plugin zeichnet (unter vielen anderen) Blockdiagramme, Gant-Charts, UML-Diagramme, Mockups und Bindmaps, oder rendert BPMN-Diagramme aus dem Source-Code in die Doku ein, damit dort stets die aktuellste Version enthalten ist. Dazu verwendet es wiederum andere Tools wie PlantUML.

auch Diagramme lassen sich in Textform generieren

• wer Screenshots für eine Benutzerdokumentation braucht, kann diese über Asciidoctor-Screenhots automatisch erzeugen und in die Doku einbetten lassen. So verlieren auch umfangreiche Redesigns ihren Schrecken.
• wenn nicht alle Kollegen direkt vom Docs-As-Code-Ansatz überzeugt sind, dann hilft vielleicht das Office-Plugin weiter: es kann Tabellen aus Excel in Asciidoctor-Tabellen, und Powerpoint-Slides in Bilder konvertieren und einbetten.

Doku + Code = ❤️

Es hat durchaus seine Vorteile, wenn Doku und Code zusammen in einem Repository liegen: so hat man immer die passende Doku auch für ältere Versionen zur Hand. Außerdem können Auszüge aus dem Code direkt in die Doku übernommen, und Beispiele aus der Doku mitkompiliert und getestet werden — nie wieder veraltete Codebeispiele! Und dank eingebautem Syntax-Highlighting sieht das auch noch fantastisch aus.

generierte API-Dokumentation eingebettet ins fertige Dokument

Wer OpenAPI-Annotations verwendet, kann dank Swagger2Markup die generierte API-Dokumentation mit ins Dokument übernehmen. Damit kann die API weiter direkt am Code beschrieben werden, die Doku ist immer aktuell und man muss dennoch nicht auf ein “echtes” Dokument verzichten.

Besonders gut klappt das, wenn die Dokumentation mit Bestandteil des Builds ist. Ruby-Entwickler haben es hier leicht. Asciidoctor ist in Ruby geschrieben: Das passende Gem einbinden, aufrufen, fertig. Für Java gibt es Maven- und Gradle-Plugins. Sie basieren auf AciidoctorJ, welches dank jRuby dem Ruby-Original in nichts nachsteht. Auch für Node.js gibt es eine Implementierung: Asciidoctor.js.

Der Endgegner: SharePoint

Kritisch wird es, wenn auch Nicht-Technologen mit an der Dokumentation arbeiten möchten, die vielleicht nicht so viel mit Docs-as-Code, Asciidoctor oder git anfangen können. Zwar lässt sich über Umwege wie Pandoc auch ein Word-Dokument erzeugen, aber das ist eine Einbahnstraße — Änderungen darin lassen sich praktisch nicht mehr zurück übernehmen.

Wem es aber reicht, die Dokumente zum Lesen in den gewohnten Kanälen zu veröffentlichen, für den ist vielleicht der Upload über die REST-API von OneDrive, Netzwerkmounts von Sharepoint, oder Tools wie Confluence-Publisher ein gangbarer. Persönlich finde ich, dass es sich sehr lohnt hier ein bisschen Überzeugungsarbeit zu leisten: die HTML-Output ist für die tägliche Arbeit einfach praktischer, z.B. um Kollegen schnell mal einen Link zu genau der passenden Stelle der Doku zu schicken, der auch in ein paar Wochen noch aktuell ist.

Zusammenfassung

Versteht mich bitte nicht falsch: Word macht seine Sache gut. Es ist aber ein Schreib- und Layout-Programm für einfachere Dokumente — wer versucht hat seine Abschlussarbeit damit zu schreiben, kann das bestimmt nachvollziehen. Entwickler arbeiten anders, und brauchen deshalb auch andere Tools. Wer anspruchsvolle technische Dokumente im Team schreiben möchte, für den lohnt sich auf jeden Fall ein Blick auf Asciidoctor und die Möglichkeiten, die sich damit bieten.