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
   

   View Slide

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.
   

   View Slide

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
   

   View Slide

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
   

   View Slide

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.
   

   View Slide

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
   

   View Slide

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/
   

   View Slide

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/
   

   View Slide

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.
   

   View Slide

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

    View Slide

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
    

    View Slide

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
    

    View Slide

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
    

    View Slide

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
    

    View Slide

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/
    

    View Slide

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.
    

    View Slide

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.
    

    View Slide

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
    

    View Slide

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
    

    View Slide

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
    

    View Slide