Softwareprojekte mit Antora dokumentieren
Für einzelne Dokumente ist AsciiDoc sehr praktisch. Schwieriger ist es, damit ganze Dokumentationen über mehrere Repositorys hinweg zu strukturieren und konsistent zu halten. Doch genau dafür gibt es Antora: einen Dokumentationsgenerator für statische Websites, deren Inhalte auf AsciiDoc basieren.
Softwaredokumentation ist wichtig – allen faulen Ausreden zum Trotz. Wenn die Dokumentation alle Ebenen der Software konsistent und jeweils auf dem aktuellen Stand abbilden soll, sind vereinfachte Auszeichnungssprachen und Docs-as-Code-Ansätze unabdingbar. Das bedeutet, Dokumentation wie Quellcode zu behandeln. Zum Bearbeiten der Dokumente kann (und soll) die gleiche Entwicklungsumgebung (IDE), Versionsverwaltung, Integration in die organisatorischen und technischen Prozesse sowie die gleiche CI/CD-Pipeline wie für den eigentlichen Programmcode verwendet werden.
Klassische Auszeichnungssprachen (Markup Languages), etwa HTML und LaTeX, haben zwar den Vorteil, dass sie im Gegensatz zu Formaten, wie sie beispielsweise Office-Programme produzieren, sämtliche Einstellungen und Parameter offenlegen und somit für Menschenaugen erkennbar machen. Sie sind aber dennoch oft schwer zu lesen und umständlich zu schreiben. Vereinfachte Auszeichnungssprachen (Lightweight Markup Languages) hingegen besitzen eine einfachere Syntax, die den Schreib- und Lesefluss nicht stört, was sie für den Docs-as-Code-Ansatz prädestiniert. Was dann noch fehlt, ist ein Werkzeug, das diesen Ansatz auch in umfangreichen Softwareprojekten handhabbar macht. Genau das ist Antora: Es führt Inhalte aus beliebig vielen Quellen zusammen, strukturiert sie und generiert daraus statische und versionierte Dokumentationswebsites, durch die via Browser offline wie auch online navigiert werden kann.