Online-Dokumentation für Nutzer mit AsciiDoc und Antora

Antora erstellt Dokumentations-Websites für Nutzer. Gemäß des Docs-as-Code-Ansatzes werden alle Inhalte in AsciiDoc-Dateien in Git-Repositories versioniert und über CI/CD publiziert.

Die Nutzer erhalten eine übersichtliche Darstellung der Dokumentation im Browser mit Navigationsleiste, Suche und Querverweisen. Sie können zwischen verschiedenen Versionen der Dokumentation hin- und herschalten, um die für sie passenden Informationen zu finden. Open-Source-Projekte wie Camel, Debezium und Couchbase nutzen diese Lösung bereits.
Entwickler und Autoren der Dokumentation bearbeiten die Inhalte wie gewohnt in ihrer IDE und versionieren die Inhalte in der Versionsverwaltung mit Git. Alle Änderungen durchlaufen die bestehenden Code-Review- und Build-Prozesse des Projekts.

Dieser Vortrag stellt die Grundlagen eines Antora-Setups vor und zeigt alle Schritte von einer Dokumentationsänderung in der IDE bis hin zur aktualisierten Dokumentations-Website mit Continuous Integration und Delivery.

Transcript

1. Online-Dokumentation für Nutzer mit AsciiDoc® und Antora Alexander Schwartz, Principal Software Engineer ObjektForum (OnlineEdition) | 2022-06-20
2. CC BY-NC-SA 4.0 | Online-Dokumentation für Nutzer mit AsciiDoc und Antora | Juni 2022 | Alexander Schwartz 2 Online-Dokumentation für Nutzer mit AsciiDoc und Antora Dokumentation unterstützt die Nutzer 1. AsciiDoc and Antora in Aktion 2. Einrichten von Antora 3. Zusammenfassung 4.
3. 3 Motivation Inhalte sind aktuell. Inhalte sind konsistent. Neue Funktionen und ihre Dokumentation sind gleichzeitig live. CC BY-NC-SA 4.0 | Online-Dokumentation für Nutzer mit AsciiDoc und Antora | Juni 2022 | Alexander Schwartz Dokumentation unterstützt die Nutzer bei ihrer Arbeit
4. • Online, automatisiert, aktuell • Durchsuchbar and themen-basiert • Navigation und Querverweise • Gruppiert nach Version und Komponente CC BY-NC-SA 4.0 | Online-Dokumentation für Nutzer mit AsciiDoc und Antora | Juni 2022 | Alexander Schwartz 4 Dokumentation unterstützt die Nutzer bei ihrer Arbeit Warum AsciiDoc und Antora
5. CC BY-NC-SA 4.0 | Online-Dokumentation für Nutzer mit AsciiDoc und Antora | Juni 2022 | Alexander Schwartz 5 Online-Dokumentation für Nutzer mit AsciiDoc und Antora Dokumentation unterstützt die Nutzer 1. AsciiDoc and Antora in Aktion 2. Einrichten von Antora 3. Zusammenfassung 4.
6. 6 CC BY-NC-SA 4.0 | Online-Dokumentation für Nutzer mit AsciiDoc und Antora | Juni 2022 | Alexander Schwartz Antora liefert Struktur und Werkzeuge zur Automatisierung • Strukturiert Dokumentation in Komponenten und Module • Sammelt AsciiDoc-Inhalte aus verschiedenen Git-Repositories und Branches • Konvertiert AsciiDoc Inhalte in HTML • Verbindet das HTML mit dem UI Theme und erzeugt eine statische Web-Site Hauptvorteile: • Schnelle Konvertierung auf Basis von Node.js mit wenigen abhängigen Modulen • Modular und erweiterbar
7. CC BY-NC-SA 4.0 | Online-Dokumentation für Nutzer mit AsciiDoc und Antora | Juni 2022 | Alexander Schwartz 7 AsciiDoc ist die Sprache, Asciidoctor ist das Werkzeug Asciidoctor https://asciidoctor.org/ AsciiDoc® • Schreiben ohne Ablenkung mit einfachem Text • Großer Funktionsumfang für technische Dokumentation • Seit über 15 Jahren verfügbar und weiterentwickelt • Standardisierung in 2020 bei der Eclipse Foundation begonnen Asciidoctor • Werkzeug, das aus den AsciiDoc-Textdateien HTML und viele andere Format erstellt • Open Source • Läuft in Java, Ruby und JavaScript Laufzeitumgebungen • Genutzt von Antora für die AsciiDoc-zu-HTML Konvertierung https://asciidoc-wg.eclipse.org/
8. • Fokussiert bleiben und die Anwendung nicht wechseln • Zusammenarbeit über die Versionsverwaltung • IntelliJ AsciiDoc Plugin bietet Unterstützung für Antora und AsciiDoc CC BY-NC-SA 4.0 | Online-Dokumentation für Nutzer mit AsciiDoc und Antora | Juni 2022 | Alexander Schwartz 8 Schreiben in der IDE List of editors: https://asciidoctor.org/docs/editing-asciidoc-with-live-preview/
9. CC BY-NC-SA 4.0 | Online-Dokumentation für Nutzer mit AsciiDoc und Antora | Juni 2022 | Alexander Schwartz 9 Online-Dokumentation für Nutzer mit AsciiDoc und Antora Dokumentation unterstützt die Nutzer 1. AsciiDoc and Antora in Aktion 2. Einrichten von Antora 3. Zusammenfassung 4.
10. CC BY-NC-SA 4.0 | Online-Dokumentation für Nutzer mit AsciiDoc und Antora | Juni 2022 | Alexander Schwartz 10 Antora: Struktur • Mehrere unabhängige Components • Components definiert über Name and Version • Jede Component kann mehrere Module haben • Jedes Modul hat vordefinierte Gruppen (families) für Seiten (pages), Bilder (images), Beispiele (examples), Anhänge (attachments) und Abschnitte, die an mehreren Stellen eingebunden werden können (partials) Erweitere Funktion: Komponenten können über mehrere Ordner, Branches und Repositories verteilt werden. Component images pages partials Module … …
11. Git Repo CC BY-NC-SA 4.0 | Online-Dokumentation für Nutzer mit AsciiDoc und Antora | Juni 2022 | Alexander Schwartz 11 Antora: Ablauf Was die Nutzer machen: 1. Antora starten Was Antora macht: 1. Antora Playbook laden mit der Liste der Repositories und Branches 2. Git Repository clonen 3. AsciiDoc in HTML wandeln 4. Mit UI-Theme und UI-Anpassungen verbinden 5. Optional: Suchindex erstellen 6. Im Ausgabeverzeichnis eine statische Website erstellen Playbook Git Repo Antora Static Site UI Theme
12. Rolle Professionelle Fähigkeiten Technische Fähigkeiten Autor Strukturieren und Schreiben • Git (für die Zusammenarbeit mit anderen Autoren) • AsciiDoc (um Inhalte zu erstellen) CC BY-NC-SA 4.0 | Online-Dokumentation für Nutzer mit AsciiDoc und Antora | Juni 2022 | Alexander Schwartz 12 Antora: Rollen
13. Rolle Professionelle Fähigkeiten Technische Fähigkeiten Autor Strukturieren und Schreiben • Git (für die Zusammenarbeit mit anderen Autoren) • AsciiDoc (um Inhalte zu erstellen) Docu Ops Automatisierung und Infrastruktur • Git (für die erstmalige Einrichtung) • YAML (für die Konfiguration) • package.json (für Versionsmanagement) • Continuous Integration (für Automatisierung) CC BY-NC-SA 4.0 | Online-Dokumentation für Nutzer mit AsciiDoc und Antora | Juni 2022 | Alexander Schwartz 13 Antora: Rollen
14. Rolle Professionelle Fähigkeiten Technische Fähigkeiten Autor Strukturieren und Schreiben • Git (für die Zusammenarbeit mit anderen Autoren) • AsciiDoc (um Inhalte zu erstellen) Docu Ops Automatisierung und Infrastruktur • Git (für die erstmalige Einrichtung) • YAML (für die Konfiguration) • package.json (für Versionsmanagement) • Continuous Integration (für Automatisierung) Web Developer Web Site Erstellung • HTML/CSS (um das Antora Theme anzupassen) CC BY-NC-SA 4.0 | Online-Dokumentation für Nutzer mit AsciiDoc und Antora | Juni 2022 | Alexander Schwartz 14 Antora: Rollen
15. CC BY-NC-SA 4.0 | Online-Dokumentation für Nutzer mit AsciiDoc und Antora | Juni 2022 | Alexander Schwartz Autor: 1. Erstellt erste Ordner-Struktur für erste Component 2. Erstellt antora.yml und vergibt Name und Version 3. Erstellt index.adoc im Verzeichnis pages 4. Erstellt Navigationseinträge in nav.adoc und fügt es zu antora.yml hinzu Docu Ops: 1. Installiert Antora (z. B. npm CLI oder package.json) 2. Erstellt Playbook für den Autor für eine lokale Vorschau 3. Erstellt Playbook das die Website für das Internet erstellt Web Developer: 1. Kopiert das bestehende UI-Theme (oder erstellt ein eigenes) 2. Legt UI-Anpassungen im Ordner supplemental_ui ab. 15 Antora: Erste Schritte 📒 my-component ├─📄 antora.yml └─📂 modules ├─📂 ROOT │ ├─📂 attachments │ ├─📂 examples │ ├─📂 images │ ├─📂 pages │ │ └─📄 index.adoc │ ├─📂 partials │ └─📄 nav.adoc └─📂 a-named-module └─📂 pages Quick Start Guide: https://docs.antora.org/antora/latest/install-and-run-quickstart/
16. CC BY-NC-SA 4.0 | Online-Dokumentation für Nutzer mit AsciiDoc und Antora | Juni 2022 | Alexander Schwartz 16 Zeit für eine Live-Demo! Wie alles zusammenspielt am Beispiel des IntelliJ AsciiDoc Plugins.
17. CC BY-NC-SA 4.0 | Online-Dokumentation für Nutzer mit AsciiDoc und Antora | Juni 2022 | Alexander Schwartz 17 Online-Dokumentation für Nutzer mit AsciiDoc und Antora Dokumentation unterstützt die Nutzer 1. AsciiDoc and Antora in Aktion 2. Einrichten von Antora 3. Zusammenfassung 4.
18. 18 Warum AsciiDoc und Antora Inhalte sind aktuell durch Zusammenarbeit im Team über Versionskontrolle in Git. Inhalte sind konsistent durch Komponentenversionen und de-duplizierung von Inhalten. Neue Funktionen und ihre Dokumentation sind gleichzeitig live durch CI/CD Werkzeuge und automatisiertes Publizieren. CC BY-NC-SA 4.0 | Online-Dokumentation für Nutzer mit AsciiDoc und Antora | Juni 2022 | Alexander Schwartz Dokumentation unterstützt die Nutzer bei ihrer Arbeit
19. AsciiDoc® https://asciidoc.org/ Asciidoctor https://asciidoctor.org/ IntelliJ AsciiDoc Plugin https://intellij-asciidoc-plugin.ahus1.de/ PlantUML https://plantuml.com/ https://real-world-plantuml.com/ CC BY-NC-SA 4.0 | Online-Dokumentation für Nutzer mit AsciiDoc und Antora | Juni 2022 | Alexander Schwartz 19 Links @ahus1de Antora https://antora.org/ Videos, Folien und Beispiele https://www.ahus1.de/post/asciidoctor-intro-and-deep-dive https://www.ahus1.de/post/cdc-antora-live https://www.ahus1.de/post/documentation-site-antora Asciidoctor Kroki Extension https://github.com/Mogztter/asciidoctor-kroki
20. Kontakt Alexander Schwartz Principal Software Engineer +49 172 6752068 alexander.schwartz@gmx.net @ahus1de CC BY-NC-SA 4.0 | Online-Dokumentation für Nutzer mit AsciiDoc und Antora | Juni 2022 | Alexander Schwartz 20