Über unsMediaKontaktImpressum
Ralf D. Müller & Dr. Gernot Starke 05. Februar 2019

Docs-as-Code – Die Grundlagen

Schlechte Dokumentation kostet Geld

Eine großangelegte Umfrage zu Open Source zeigt, dass unvollständige oder verwirrende Dokumentation zu den Hauptproblemen freier Software zählt [1]. Das gilt neben Anwendungsdokumentation insbesondere auch für technische Dokumentation, etwa von Softwarearchitektur. Diese Aussage können wir sicherlich verallgemeinern: schlechte Dokumentation von Software erschwert Änderung, Support und letztlich auch Nutzung. Wir möchten hier auf technische Dokumentation von Software abzielen, also beispielsweise Entwicklungs-, Architektur- und Betriebsdokumentation. Das Thema Anwendungsdokumentation klammern wir bewusst aus.

Unserer Erfahrung nach behindern eine ganze Reihe von Faktoren die Erstellung und kontinuierliche Pflege technischer Dokumentation:

  1. Ungeeignete Werkzeuge, die ursprünglich nicht für die Erstellung und Pflege solcher Dokumentation gedacht waren.
  2. Geringe Motivation seitens der Entwicklungsteams, oftmals verstärkt durch die oben genannten Defizite der entsprechenden Werkzeuge.
  3. Unklare Vorstellung über Struktur, Form und Inhalt von Dokumentation: Entwicklungsteams haben keine klare Vorstellung davon, was und wie sie dokumentieren sollen.
  4. Schlechte Vorlagen ("Templates") für Dokumentation.

Technische Dokumentation als "Leichtgewicht"

Stellen Sie sich vor, Sie erstellen und pflegen Ihre technische Dokumentation genau so wie auch Ihren Quellcode: Im selben Texteditor oder einer IDE, als reiner Text, versioniert in Ihrem Lieblings-Repository (wir mögen Git). Dann verschwindet für Entwicklungsteams das erste der oben genannten Probleme (nämlich die ungeeigneten Werkzeuge), und die Motivation zur Erstellung und Pflege von Doku wird auch gleich besser.

Wir zeigen Ihnen genau diesen Ansatz: Integrieren Sie das bisher ungeliebten Thema Dokumentation mit Hilfe robuster Open-Source-Werkzeuge einfach und effektiv in Ihre Softwareentwicklung, mit Hilfe Ihres favorisierten Texteditors. Mergen und branchen Sie Dokumentation genau wie Quellcode. Statt binäre Dokumente per E-Mail zu versenden und Versionsnummern und Namenskürzel an die Dateinamen zu hängen, checken Sie Ihre Dokumentation per Commit und push ein, mit derselben Branching-Strategie, mit der Sie auch Ihre Software entwickeln.

Damit können Sie ein breites Spektrum technischer Dokumentation von Software abdecken, beispielsweise Entwicklungs-, Architektur- oder auch Betriebsdokumentation. Wir persönlich haben auch Anforderungs- und Userdokumentation auf diese Weise erstellt. Für diesen Ansatz hat sich im Netz der Begriff Docs-as-Code etabliert – also Dokumentation genauso wie Quellcode behandeln [2].

Mit Docs-as-Code reduzieren Sie die lästigen Hemmschwellen, die durch Werkzeugwechsel und/oder Medienbrüche aufgetreten sind. Sie können Dokumente beliebig aufteilen (sprich: im Team arbeitsteilig angehen), und Dokumentation in den Build- und Testprozess ihrer Software integrieren. Sollten Sie in Ihrem Team bereits mit arc42 arbeiten [3], so werden Sie sich mit dem Docs-as-Code-Ansatz besonders wohl fühlen. Andere Beteiligte (Stakeholder) dürfen ihre favorisierten Tools wie Word, Powerpoint, Excel oder auch Enterprise-Architect weiter verwenden, denn Docs-as-Code kann automatisiert eine Vielzahl anderer Dokumenttypen integrieren (darauf gehen wir im zweiten Teil dieses Artikels detailliert ein).

Falls das für Sie attraktiv klingt – herzlich willkommen! Wir haben diese Ansätze bereits mehrfach in der Praxis erfolgreich einsetzen dürfen und einige unserer Erfahrungen in diesem und den folgenden Artikeln verarbeitet.

Sie finden Docs-as-Code in drei Teilen erläutert:

  • Teil 1 – Die Grundlagen: In der vorliegenden Folge zeigen wir Ihnen AsciiDoc als unsere favorisierte Grundlage für technische Dokumentation. Sie erfahren allerhand über Gliederung, Formatierung, Modularisierung, Integration von Diagrammen und Quellcode.
  • Teil 2 – In der zweiten Folge lernen Sie docToolchain kennen, die Open-Source-Lösung zur Unterstützung des Docs-as-Code-Ansatzes [4]. Sie lernen die Integration von Office-Dokumenten, Confluence und Enterprise-Architect in Ihre Dokumentation kennen.
  • Teil 3 – In der dritten Folge bringen wir alles unter ein Dach: Sie erfahren, wie Sie die verschiedenen Arten von Dokumentation (etwa Architektur- und Entwicklungsdokumentation sowie User-Manuals, Tutorials etc) im Rahmen einer integrativen Website zusammenführen können.

Sämtlichen Quellcode und Beispiele aller drei Teile finden Sie in öffentlichen Repositories bei Github [5].

So sieht’s aus

Um Ihnen das manchmal ungeliebte Thema Dokumentation etwas schmackhaft zu machen, möchten wir Ihnen einen Ausblick auf das mögliche Endergebnis geben: Eine Website, auf der Sie drei verschiedene Typen von Dokumentation unter einem (homogenen) Dach vereinigt finden.

In der Navigationsleiste der Website (Abb. 1) finden Sie drei typische Arten von Dokumentation, nämlich "User-Guide" (Benutzungsanleitung o. ä.), "Development Guide" (detaillierte Informationen für das Entwicklungsteam) sowie die Architekturdokumentation, beispielsweise auf Basis des arc42 Templates.

Die gesamte Seite wird nach dem Motto "drink your own champagne" generiert [6], sämtliche Quellen liegen unter Versionsverwaltung und sind im Github-Repository öffentlich [7].

Bestandteile technischer Dokumentation

Für technische Dokumentation benötigen Sie die üblichen Verdächtigen, nämlich Überschriften, Fließtext mit Auszeichnungen wie fett und kursiv sowie Tabellen, Diagramme und Querverweise. Uns helfen oft Codebeispiele (am besten inkludiert aus dem Original-Code-Repository) und am besten soll unsere Dokumentation modular aufgebaut und flexibel kombiniert werden können. Lassen Sie uns Schritt für Schritt starten:

Dokumentation als "plain text"

Der Schlüssel zum Docs-as-Code-Ansatz ist die Verwendung eines plain-text-Formats anstelle der Binärformate typischer Textverarbeitungen oder Office-Anwendungen. Nur so können Sie Ihre Dokumentation tatsächlich wie Code behandeln und verwalten.

Nutzen Sie das das leichtgewichtige und seit vielen Jahren bewährte Markup-Format Asciidoc als Grundlage [8]. Im Gegensatz zum ebenfalls weit verbreiteten Markdown handelt es sich bei AsciiDoc um einen wirklichen Standard, ohne Fragmentierung durch unterschiedliche Dialekte. AsciiDoc ist sowohl einfach als auch funktional mächtig und Sie können damit alle Arten von Dokumentation erstellen, bei Bedarf sogar Bücher damit schreiben.

Für AsciiDoc gibt es einen Open-Source- – d. h. frei verfügbaren – Konverter namens Asciidoctor [9], der AsciiDoc in verschiedene Zielformate (etwa HTML oder DocBook) konvertieren kann und auf verschiedenen Plattformen läuft.

In Abb. 2 finden Sie eine Übersicht:

  1. Verschiedene Beteiligte, etwa das Entwicklungsteam oder die ArchitektInnen, erstellen jeweils Teile der Dokumentation, sowohl in Textform als AsciiDoc-Dateien, als auch Diagramme.
  2. Ein Build-Prozess kombiniert und konvertiert diese einzelnen Teile zu den gewünschten Zielformaten, beispielsweise HTML oder PDF. In Folge 2 dieses Artikels zeigen wir Ihnen, wie Sie sehr einfach auch Confluence, docx oder andere Formate erzeugen können.
  3. Andere Stakeholder arbeiten weiterhin in ihren etablierten Werkzeugen, etwa Word. Deren Dokumentation liegt in Office-Formaten, etwa docx, pptx oder xlsx vor.
  4. Die docToolchain (genauer erklärt in Folge 2) integriert ebenfalls solche Formate.

Aber jetzt wird es Zeit für konkrete Details. Sie werden sehen, dass Schreiben mit AsciiDoc wirklich einfach geht:

Überschriften

Erzeugen Sie Überschriften einfach durch ein vorangestelltes =, wobei die Überschriftenebene der Anzahl der =-Zeichen entspricht. Ein einzelnes = ist dem Buchtitel oder Dokumentnamen vorbehalten, so dass ein normaler Text mit == als erste Überschriftenebene beginnt.

Absätze

AsciiDoc ignoriert einfache Zeilenumbrüche und erkennt erst nach einer Leerzeile einen Absatz. Dieser Mechanismus hilft beim Strukturieren von Texten. Möchten Sie dennoch gezielt einen Zeilenumbruch setzen, so beenden Sie die Zeile mit einem Leerzeichen und +.

Textformate

Text können Sie in den "üblichen" Formaten darstellen. Darüber hinaus bietet AsciiDoc die Möglichkeit, beliebige CSS-Styles anzuwenden, aber das sprengt den Rahmen dieser kompakten Einführung.

Listen

Sowohl Listen als auch (nummerierte) Aufzählungen funktionieren mit AsciiDoc intuitiv.

AsciiDoc bietet noch eine Vielzahl weiterer Möglichkeiten für solche Auflistungen an, mehr Details finden Sie in der Original-Dokumentation [10].

Links und Verweise

URLs können Sie einfach schreiben, sie werden von Asciidoctor als solche erkannt und im Zielformat (beispielsweise HTML) entsprechend verlinkt. Möchten Sie die URL im Text durch einen Text ersetzen, so hängen Sie diesen in eckigen Klammern einfach an.

Relative Verweise zwischen mehreren Dokumenten kann Asciidoctor aufgrund der fehlenden Protokollbezeichnung nicht automatisch erkennen. Setzen Sie einfach ein link: davor und leere Klammern [] dahinter und alles ist wie gehabt.

AsciiDoctor unterstützt auch Querverweise innerhalb des Dokuments. Mit doppelten eckigen Klammern [[ein-anker]] setzen Sie Anker im Dokument, auf den Sie mit spitzen Klammern <<ein-anker>> verweisen. Wie Asciidoctor die Referenz benennt, steuern Sie über das Attribut :xrefstyle:.

Asciidoctor setzt übrigens viele Anker als Sprungziele für Überschriften, Tabellen und Bilder automatisch. Das vereinfacht Querverweise erheblich, weil Sie diese Sprungziele nicht mehr manuell definieren müssen (aber Vorsicht: wenn Sie eine Überschrift umbenennen, so ändert sich damit auch der automatisch erzeugte Anker!).

Bilder und Diagramme

Bilder und Diagramme können Sie ähnlich wie Querverweise einfügen – stellen Sie einfach das Wort image voran: In der folgenden Tabelle zeigen wir Ihnen gleich noch die Möglichkeiten der Skalierung von Bildern.

Diagramme und Bilder stellen wichtige Elemente technischer Dokumentation dar, weil sie Zusammenhänge aufzeigen und Überblick ermöglichen. Oftmals erstellen Sie Diagramme in einem speziell dafür vorgesehenen Werkzeug. Sie sind aber immer nur die Darstellung der Daten einer Quelle. Binden Sie nur die Bilder in Ihre Dokumentation ein, so geht automatisch der enge Bezug zur Quelle verloren.

Für einfache UML-Diagramme schlagen wir Ihnen eine elegante Lösung namens PlantUML vor: Damit beschreiben Sie Ihr Diagramm textuell und überlassen es Asciidoctor, das Diagramm in ein Bild zu wandeln. Unter der Haube nutzt AsciiDoctor dafür den Open-Source-Konverter PlantUML, der die textuelle Syntax in Grafikformate wie svg oder png verwandelt (wir empfehlen aus Erfahrung png).

Quellcode

In Ihrer technischen Dokumentation werden Sie an einigen Stellen Quellcode oder zumindest Code-Fragmente einfügen und erklären wollen.

AsciiDoc bietet dafür sehr leistungsfähige Möglichkeiten. Beginnen wir mit der reinen Darstellung von Quellcode: Syntax-Highlighting, Zeilennummern und Markierungen, damit können Sie schon eine ganze Menge anstellen.

Beachten Sie bei der Verwendung der sogenannten Callouts // <1>, daß Sie das Attribut :icons: font gesetzt haben. Dadurch werden die Callouts so dargestellt, dass sie beim Kopieren des Textes nicht mitkopiert werden und somit nicht stören.

Textkästen (Sidebars)

Manchmal möchten Sie Inhalte besonders hervorheben. Gerade bei technischer Dokumentation bietet es sich an, den einen oder anderen Sachverhalt außerhalb des Fließtextes zu erklären. Verwenden Sie in solchen Fällen eine Sidebar (Textkasten).

Tabellen

Tabellen leiten Sie mit |=== ein. Sie können in eckigen Klammern Optionen zur Darstellung der Tabelle angeben. Spalten trennen Sie mit |.

Jetzt möchten wir die Spaltenbreite der Tabelle beeinflussen. Eine Möglichkeit ist es, die relative Breite einer Spalte in der cols=-Definition anzugeben. Das funktioniert ebenfalls mit prozentualen Angaben. Beachten Sie, dass Sie durch die Definition der Spaltenzahl in den Optionen, die Zellen einfach untereinander schreiben können. Das sorgt für eine bessere Übersicht und leichtere Bearbeitung der Tabelle.

Der AsciiDoctor Writers' Guide hält noch eine Reihe weiterer Möglichkeiten bereit – Spalten- und Zeilenformatierung, links- und rechtsbündige Spalten und so weiter .

Modulare Dokumentation

Im Normalfall möchten Sie gemeinsam mit Ihrem Team an Dokumentation arbeiten, d. h. Sie müssen Dokumente modularisieren. In AsciiDoc geht das sehr elegant, nämlich durch die include-Anweisung. Sie können Dokumentation damit in kleine Teile zerlegen, im Team getrennt bearbeiten und bei Bedarf an beliebigen Stellen wieder einfügen (s. Abb. 15).

Falls Sie etwa die Architektur eines Systems mit Hilfe des arc42-Templates pragmatisch dokumentieren möchten, so können Sie die einzelnen Sektionen von arc42 in jeweils einzelnen Dateien speichern und flexibel aus einem Master-Dokument inkludieren, ganz ohne Redundanz. Für umfassende Dokumentation können Sie Teile der modularisierten Dokumentation sogar problemlos an mehreren Stellen verwenden (s. Abb. 16).

Wir nutzen das für sogenannte Architecture Decision Records (ADRs), mit deren Hilfe wir Implementierungs- oder Architekturentscheidungen zuerst im Team diskutieren (und sie in der Entwicklungsdokumentation informell als eine AsciiDoc-Datei festhalten). Stellt sich später heraus, dass sie besondere Relevanz in der Architektur besitzen, so können wir diese Datei problemlos an passender Stelle in unserer Dokumentation inkludieren.

Ausgabeformat generieren

Das mit AsciiDoc am häufigsten verwendete Ausgabeformat ist sicherlich HTML. Wenn Sie sich AsciiDoc und Asciidoctor einfach mal ansehen wollen, dann bietet sich asciidoclive.com an [12]. Auf dieser Website können sie AsciiDoc im Browser auf einer Seite editieren, und sehen unmittelbar daneben das daraus generierte Ergebnis. Unter der Haube läuft dort die JavaScript-Version von Asciidoctor. Wenn Sie die Kommandozeile für die Konvertierung bevorzugen, dann gibt es z. B. asciidoctorj, das Sie beispielsweise über sdkman.io installieren können [13].

Nach den ersten Gehversuchen empfehlen wir Ihnen, die Konvertierung direkt in Ihren Software-Build zu integrieren – und damit Ihre Dokumentation von nun an genauso wie Ihre Software bauen zu lassen (über Möglichkeiten zum Test der Dokumentation schreiben wir in der nächsten Folge dieses Artikels). Für diese Integration existieren wir diverse Plugins, beispielsweise für Gradle und Maven. Mit der Standard-Konfiguration reicht in Gradle sogar ein Einzeiler, nämlich die Definition des Plugins:

In unserem Github-Repository finden Sie ein etwas erweitertes Beispiel, das schon plantUML unterstützt. Persönlich verwenden wir für unsere Docs-as-Code Einsätze am liebsten Gradle [14]. Sollte Ihnen HTML als Ausgabeformat nicht reichen, so kann Asciidoctor noch docBook erzeugen [15], und über ein Plugin auch PDF. Wie Sie weitere Ausgabeformate erzeugen können, zeigen wir Ihnen dann im zweiten Teil unserer Reihe.

Dokumentation mit (UML-) Modellierungstools?

Werkzeuge wie Enterprise-Architect, VisualParadigm und andere unterstützen bei der Erstellung von UML-Diagrammen. Für textuelle oder tabellarische Dokumentation halten wir diese Tools für wenig geeignet, außerdem liegt die Einstiegshürde für Entwicklungsteams aufgrund der hohen Komplexität dieser Tools ungemein hoch.

Einige UML-Tools besitzen jedoch leistungsfähige Schnittstellen zur Automatisierung, so dass sie mit Docs-as-Code Ansätzen gut zusammen arbeiten können. Lesen Sie dazu mehr im zweiten Teil dieses Artikels.

Fazit

Sie können technische Dokumentation auf Basis von "plain-text" erstellen, Grafiken inkludieren und alles mit Hilfe Ihrer Versionsverwaltung synchron mit dem Quellcode Ihrer Systeme pflegen. Teamfähigkeit (review, branch, merge etc.) bekommen Sie damit fast geschenkt, die Integration in den Buildprozess ebenso.

Die Einstiegshürde zur Erstellung wirkungsvoller Dokumentation sinkt bei Entwicklungsteams damit beträchtlich – damit steigt die Chance, dass langfristig relevante Informationen auch wirklich dokumentiert werden und nicht in den Köpfen von Entwicklungsteams dem Vergessen anheim fallen. Durch den Ansatz stellen Sie weiterhin sicher, dass jeder weiß, wo die Dokumentation liegt: beim Code – da wo sie hingehört.

Mit dem in diesem Artikel beschriebenen Ansatz sind Sie schon voll gerüstet für Docs-as-Code. In der zweiten Folge dieses Artikels zeigen wir Ihnen, wie wir noch einen Schritt weiter gehen und mit Hilfe der frei verfügbaren Werkzeugkette docToolchain Office-Dokumente integrieren, Word- und Confluence-Formate generieren und noch andere spannende Dinge erledigen können. Eben das, was Sie auch mit Code machen würden: extrahieren, generieren, transformieren, testen etc.

In diesem Sinne: viel Erfolg mit Docs-as-Code!

Quellen
  1. Umfrage zu Open Source 
  2. Docs-as-Code
  3. Webseite arc42
    Informatik Aktuell – Dr. Gernot Starke: arc42 – Architekturen effektiv kommunizieren
  4. docToolchain
  5. Quellcode und Beispiele: git repository
  6. Wikipedia: drink your own champagne
  7. htmlSanityCheck: git repository
  8. Wikipedia: AsciiDoc-Format
  9. AsciiDoctor
  10. Original-Dokumentation
  11. AsciiDoctor Writers' Guide
  12. AsciiDocLIVE
  13. sdkman.io
  14. Gradle
  15. docBook

Weitere Informationen

Hinweis: Alle Grafiken © Ralf D. Müller & Dr. Gernot Starke

Autoren

Ralf D. Müller

Ralf D. Müller ist ambitionierter Groovy-Entwickler und versucht stetig, seine Arbeit weiter zu vereinfachen. Deshalb hat er das Open-Source-Projekt docToolchain ins Leben gerufen.
>> Weiterlesen

Dr. Gernot Starke

Dr. Gernot Starke unterstützt als innoQ-Fellow Kunden und Projekte in unterschiedlichen Branchen bei Architektur- und Reviewaufgaben. Er ist (Mit-)Gründer und Committer von arc42, Gründer und Committer von aim42.org sowie Autor...
>> Weiterlesen
Bücher des Autors:

botMessage_toctoc_comments_9210