Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Online-Dokumentation für Nutzer mit AsciiDoc und Antora

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.

5f528a3f6814d28b583f31842e3e8d9e?s=128

Alexander Schwartz

August 21, 2021
Tweet

Transcript

  1. Online-Dokumentation für Nutzer mit AsciiDoc und Antora Alexander Schwartz, Principal

    IT Consultant FrosCon (Virtual), 2021-02-22
  2. Motivation Inhalte sind aktuell. Inhalte sind konsistent. Neue Funktionen und

    ihre Dokumentation sind gleichzeitig live. © msg | August 2021 | Online-Dokumentation für Nutzer mit AsciiDoc und Antora | Alexander Schwartz Dokumentation unterstützt die Nutzer bei ihrer Arbeit 3
  3. © msg | August 2021 | Online-Dokumentation für Nutzer mit

    AsciiDoc und Antora | Alexander Schwartz 4 Dokumentation unterstützt die Nutzer bei ihrer Arbeit Warum AsciiDoc und Antora • Online, automatisiert, aktuell • Durchsuchbar and themen-basiert • Navigation und Querverweise • Gruppiert nach Version und Komponente
  4. 6 © msg | August 2021 | Online-Dokumentation für Nutzer

    mit AsciiDoc und Antora | 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
  5. © msg | August 2021 | Online-Dokumentation für Nutzer mit

    AsciiDoc und Antora | 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 AsciiDoc Eclipse Working Group
  6. • Fokussiert bleiben und die Anwendung nicht wechseln • Zusammenarbeit

    über die Versionsverwaltung • IntelliJ AsciiDoc Plugin bietet Unterstützung für Antora und AsciiDoc © msg | August 2021 | Online-Dokumentation für Nutzer mit AsciiDoc und Antora | Alexander Schwartz 8 Schreiben in der IDE List of editors: https://asciidoctor.org/docs/editing-asciidoc-with-live-preview/
  7. © msg | August 2021 | Online-Dokumentation für Nutzer mit

    AsciiDoc und Antora | 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 … …
  8. Git Repo © msg | August 2021 | Online-Dokumentation für

    Nutzer mit AsciiDoc und Antora | 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
  9. © msg | August 2021 | Online-Dokumentation für Nutzer mit

    AsciiDoc und Antora | Alexander Schwartz 12 Antora: Rollen Rolle Professionelle Fähigkeiten Technische Fähigkeiten Autor Strukturieren und Schreiben • Git (für die Zusammenarbeit mit anderen Autoren) • AsciiDoc (um Inhalte zu erstellen)
  10. © msg | August 2021 | Online-Dokumentation für Nutzer mit

    AsciiDoc und Antora | Alexander Schwartz 13 Antora: Rollen 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)
  11. © msg | August 2021 | Online-Dokumentation für Nutzer mit

    AsciiDoc und Antora | Alexander Schwartz 14 Antora: Rollen 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)
  12. © msg | August 2021 | Online-Dokumentation für Nutzer mit

    AsciiDoc und Antora | 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 📒 📄 📂 📂 📂 📂 📂 📂 📄 📂 📄 📂 📂 Quick Start Guide: https://docs.antora.org/antora/2.3/install-and-run-quickstart/
  13. © msg | August 2021 | Online-Dokumentation für Nutzer mit

    AsciiDoc und Antora | Alexander Schwartz 16 Zeit für eine Live-Demo! Wie alles zusammenspielt am Beispiel des IntelliJ AsciiDoc Plugins.
  14. 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. © msg | August 2021 | Online-Dokumentation für Nutzer mit AsciiDoc und Antora | Alexander Schwartz Dokumentation unterstützt die Nutzer bei ihrer Arbeit 18
  15. Asciidoctor https://asciidoctor.org/ IntelliJ AsciiDoc Plugin https://intellij-asciidoc-plugin.ahus1.de/ PlantUML https://plantuml.com/ https://real-world-plantuml.com/ ©

    msg | August 2021 | Online-Dokumentation für Nutzer mit AsciiDoc und Antora | Alexander Schwartz 19 Links @ahus1de Antora https://antora.org/ Videos, slides and examples 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
  16. msg systems ag Robert-​Bürkle-Straße 1 85737 Ismaning Germany value –

    inspired by people Contact Alexander Schwartz Principal IT Consultant +49 171 5625767 alexander.schwartz@msg.group @ahus1de © msg | August 2021 | Online-Dokumentation für Nutzer mit AsciiDoc und Antora | Alexander Schwartz 20