Nach Jahren mit organisch gewachsenen Seiten im Wiki kämpften wir immer mehr mit der Lesbarkeit und der Auffindbarkeit unserer Dokumentationen. Daher entschlossen wir uns, eine spezifische Dokumentationsplattform basierend auf AsciiDoc und Antora aufzubauen.
AsciiDoc ist eine Markup Sprache, ähnlich wie Markdown. Inhalte werden als regulärer Text geschrieben und dann in ein beliebiges Ausgabeformat (HTML, PDF, …) übersetzt. AsciiDoc wurde explizit als Publishing Werkzeug für Print und Web entwickelt und bietet daher Möglichkeiten, welche bei einfacheren Sprachen nicht vorhanden sind. So können beispielsweise Referenzen innerhalb einer Seite oder auch Hinweisblöcke erstellt werden:
== Programmieren Die folgende Datei <<example>> enthält ein einfaches Programm. [#example] .example.rb [source,ruby] ---- puts 'Hello World!' ---- TIP: Du kannst obiges Beispiel mit `ruby example.rb` ausführen.
Und so sieht das gerenderte HTML aus:
Grundsätzlich ist der AsciiDoc Writer’s Guide eine gute Referenz und ein geeigneter Einstiegspunkt. Unsere Erfahrungen mit AsciiDoc waren bisher sehr positiv.
Antora
Antora ist ein Multi-Repository Site Generator für AsciiDoc. Es basiert auf Node.js und verwendet Asciidoctor, den in Ruby implementierten AsciiDoc Prozessor. Beide Tools sind Open Source.
Die Dokumentation kann mit Antora in verschiedenen Git Repositories verwaltet werden und innerhalb einer grossen Site mit einem einheitlichen User Interface publiziert werden.
In der Regel enthält ein Git Repository eine Antora Komponente, welche durch Git Branches oder Tags versioniert werden kann. Damit können verschiedene Versionen gleichzeitig publiziert werden. Komponenten sind also in sich geschlossene Dokumentationen, beispielsweise zu einem ganzen Produkt oder eine Sammlung spezifischer Leitfäden.
Innerhalb einer Komponente gibt es mehrere Module, welche zusammengehörige AsciiDoc Dateien, Bilder und andere Assets enthalten. Jede AsciiDoc Datei resultiert in einer eigenen HTML Seite, deren verschiedene Abschnitte über ein permanent sichtbares, automatisch generiertes Inhaltsverzeichnis navigierbar sind.
Die Navigation durch die verschiedenen Komponenten und Module ist frei definierbar. Wir haben uns für eine zentrale Einstiegsseite mit allen Komponenten entschieden, welche dann ihre eigene Navigation für die jeweiligen Module definieren.
Docs-as-code
Mit der neuen Plattform haben wir die Möglichkeit, unsere Dokumentation nach dem Docs-as-code Prinzip zu schreiben. D.h. wir verwenden…
… den gewohnten Editor oder die geschätzte IDE zum Bearbeiten der Dokumentation.
… Git zur Versionierung der Dokumentation.
… eine Build Pipeline zum automatisierten Bauen und Deployen der Dokumentation.
… einen Git-Workflow und Merge Requests für Reviews um die Qualität der Dokumentation sicherzustellen.
Unsere Techies können damit ihre gewohnten Werkzeuge verwenden, um die Dokumentation zu bearbeiten. Das lässt natürlich ihre Herzen höher schlagen!
Um dem Wildwuchs (Stichwort „organisches Wachstum“) Einhalt zu bieten, wurde für jedes Dokument eine verantwortliche Person definiert. Diese sorgt für die notwendige Kohärenz und überprüft die Einhaltung des Dokumentationsleitfadens. In diesem ist eine einheitliche Struktur definiert, welche den Lesenden das Auffinden von Informationen vereinfacht.
Technische Details
Unsere Dokumentation ist in verschiedene Git Repositories aufgeteilt. Über GitLab CI wird bei jedem Commit in einem der Repositories die gesamte Antora Site automatisch gebaut und deployed. Für jeden Merge Requests wird sogar eine eigene Route auf OpenShift angelegt, unter welcher dieser betrachtet werden kann.
Für die Volltextsuche in der Dokumentation verwenden wir MeiliSearch. Damit lassen sich Informationen aus allen Komponenten und Modulen schnell auffinden. Der Suchindex wird statisch beim Buildprozess generiert.
Mit diesen State-of-the-Art Setup sind wir für hervorragend lesbare, navigierbare und rasch auffindbare Dokumentationen gerüstet.