Docs-as-Code – Die Grundlagen

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].

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:

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.

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 +.

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.

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].

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 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).

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.

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 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 .

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.