Softwareprojekte konsistent mit Antora dokumentieren

Inhaltsverzeichnis

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.

iX-tract

• Antora generiert versionierte statische HTML-Seiten aus AsciiDoc-Dateien und anderen Ressourcen verschiedener lokaler und Remote-Git-Repositorys.
• Das Playbook definiert, welche Quellen Antora als Inhalt verwendet, welche Einstellungen es anwendet und wo es die Dokumentation ablegt.
• Jede Ressource erhält automatisch eine systematische Resource ID, sodass Verlinkungen unabhängig von der Quell- und Zielplattform erfolgen.
• Der lokale Kroki-Server, der im beiliegenden Docker-Image enthalten ist, kann viele textuell beschriebene Diagrammtypen rendern (Diagrams as Code).

Mehr zum Thema Softwareentwicklung

• Textbasierte Werkzeuge für Entwickler im Vergleich: Von Code zu Diagrammen
• Mit Atuin die Shell-History verwalten
• Python-Entwicklung: PyCharm und VS Code im Vergleich
• Syncfusion: UI-Komponenten für die App-Entwicklung im Test
• Dapr: Moderne verteilte Anwendungsentwicklung im Test
• Softwareprojekte mit dem Dokumentationsgenerator Antora dokumentieren
• Softwareentwicklung: Ressourcen sparen mit der C++-Funktion constexpr
• KI-gestütztes DevOps mit lokalen LLMs unterstützen
• Prozesse automatisieren mit Power Automate
• Wozu das Programmieren auf Prompt-Ebene führt
• Die kleine Codefabrik: KI-Tools für Entwickler im Überblick

Christian Heitzmann

Christian Heitzmann ist zertifizierter Softwareentwickler, Technical Writer und Trainer. Mit seiner SimplexaCode AG dokumentiert er Softwarearchitekturen für KMUs und führt Schulungen für ihre Entwickler durch.

Die englische Wikipedia führt mittlerweile über zwanzig vereinfachte Auszeichnungssprachen auf. Der bekannteste Vertreter ist wohl Markdown. MediaWiki Markup, reStucturedText und die Jira Formatting Notation sind weitere Beispiele. Der Artikel "Auszeichnungssprachen in der Softwaredokumentation" vergleicht viele dieser Sprachen mit dem Anspruch, nicht nur eine Sprache für Softwareentwicklerinnen und -entwickler, sondern für jedermann zu finden.

Das war die Leseprobe unseres heise-Plus-Artikels "Softwareprojekte konsistent mit Antora dokumentieren". Mit einem heise-Plus-Abo können sie den ganzen Artikel lesen und anhören.