Online-Dokumentation, die hilft: Strukturen, Prozesse, Tools

Mal eben etwas in der Online-Dokumentation für Nutzer ergänzen und schon ist es live? Und das so geschrieben und strukturiert, dass Nutzer wirklich davon profitieren?

Der Vortrag zeigt, welche Strukturen Nutzern helfen, wie Vorlagen das Schreiben der Dokumentation vereinfachen und das Ergebnis automatisiert geprüft werden kann.

Als Werkzeuge kommen AsciiDoc, Antora und weitere Werkzeuge aus dem Docs-as-Code Ökosystem zum Einsatz. Als Beispiel dienen verschiedene Open-Source-Projekte, und es werden öffentlich verfügbare Online-Ressourcen zum Thema vorgestellt.

Transcript

1. Online-Dokumentation, die hilft: Strukturen, Prozesse, Tools Alexander Schwartz, Principal Software Engineer @ Red Hat IT-Tage Frankfurt | 2024-12-10
2. CC BY-NC-SA 4.0 | Dezember 2024 | Online-Dokumentation, die hilft | Alexander Schwartz 3 Online-Dokumentation, die hilft Motivation 1 Dokumentation, die hilft 2 Werkzeuge 3 Zusammenfassung 4
3. CC BY-NC-SA 4.0 | Dezember 2024 | Online-Dokumentation, die hilft | Alexander Schwartz 4 Online-Dokumentation, die hilft Motivation 1 Dokumentation, die hilft 2 Werkzeuge 3 Zusammenfassung 4
4. CC BY-NC-SA 4.0 | Dezember 2024 | Online-Dokumentation, die hilft | Alexander Schwartz Motivation 5 User nutzen Dokumentation • Bevor sie eine neue Software ausprobieren → Produkthomepage • Wenn sie nicht mehr weiterwissen → Suchmaschine • Um zu verstehen, wie etwas funktioniert → Referenzdokumentation
5. CC BY-NC-SA 4.0 | Dezember 2024 | Online-Dokumentation, die hilft | Alexander Schwartz Motivation 6 Shift Left für Dokumentation • Jede*r im Entwicklungsprozess kann etwas beitragen Voraussetzung: • Wissen (Warum? Was? Wie?) • Strukturen (Vorlagen und Werkzeuge) • Prozesse (Automatisierung und Integration)
6. CC BY-NC-SA 4.0 | Dezember 2024 | Online-Dokumentation, die hilft | Alexander Schwartz 7 Online-Dokumentation, die hilft Motivation 1 Dokumentation, die hilft 2 Werkzeuge 3 Zusammenfassung 4
7. CC BY-NC-SA 4.0 | Dezember 2024 | Online-Dokumentation, die hilft | Alexander Schwartz Dokumentation die hilft 8 Suchstrategie: Die Jagd nach Antworten • Suchmaschinen: Ich lande irgendwo in der Online-Hilfe. • Ich klicke dort, wo ich die richtige Antwort vermute. • Ich bin fertig, wenn die Antwort „gut genug ist“.
8. CC BY-NC-SA 4.0 | Dezember 2024 | Online-Dokumentation, die hilft | Alexander Schwartz Dokumentation die hilft 9 Die hilfreiche Dokumentations-Website 1. Wiederkehrende Strukturen 2. Inhalte zum Überfliegen 3. Suche innerhalb der Website 4. Hierarchie und Navigation
9. CC BY-NC-SA 4.0 | Dezember 2024 | Online-Dokumentation, die hilft | Alexander Schwartz Dokumentation die hilft 10 Every Page is Page One (EPPO) Da Nutzer*innen auf jeder Seite starten können und springen: • Kontext am Anfang • In sich abgeschlossener Inhalt auf jeder Seite • Zielgerichteter Inhalt • Wissende*r Leser*in • Informationen auf einem Level • Verlinkung Mehr dazu auf: • https://everypageispageone.com/the-book/
10. CC BY-NC-SA 4.0 | Dezember 2024 | Online-Dokumentation, die hilft | Alexander Schwartz 11 Dokumentation die hilft Hierarchie (top → down) Den Einstieg erleichtern und dann mehr Informationen anbieten: • Gesamtbild / Big Picture • Erste Schritte / Getting Started • Überblicksseite / Pathfinder Topics • Schritt-für-Schritt Anleitungen / Step by Step Guides • Detailseiten / Single Step Guides
11. CC BY-NC-SA 4.0 | Dezember 2024 | Online-Dokumentation, die hilft | Alexander Schwartz 12 Dokumentation die hilft Working Backwards (bottom → up) Der Kontext zu Beginn der Seite sagt, ob man hier richtig ist: • Was Leser*innen hier erwartet • Annahmen und alternative Themen • Vorausgesetztes Wissen Auf der Seite selbst kein lineares Lesen erwarten: • Hinweise und Checkpunkte • Rücksprünge, wenn ggf. etwas ausgelassen wurde • Links zurück in der Hierarchie
12. CC BY-NC-SA 4.0 | Dezember 2024 | Online-Dokumentation, die hilft | Alexander Schwartz 13 Dokumentation die hilft Wiederkehrende Strukturen: Topic Types Vorlagen für verschiedene Seitentypen erstellen: • Lernen: Tutorial • Problemlösung: How-To/Task • Konzepte verstehen: Explanation/Concept • Informationszentriert: Reference Mehr dazu auf: • https://diataxis.fr/ • https://grafana.com/docs/writers-toolkit/structure/topic-types/ Task/Topic example:
13. CC BY-NC-SA 4.0 | Dezember 2024 | Online-Dokumentation, die hilft | Alexander Schwartz 14 Dokumentation die hilft Grundlagen Schreibstil für Online-Dokumentation Google Technical Writing https://developers.google.com/tech-writing/overview
14. CC BY-NC-SA 4.0 | Dezember 2024 | Online-Dokumentation, die hilft | Alexander Schwartz 15 Online-Dokumentation, die hilft Motivation 1 Dokumentation, die hilft 2 Werkzeuge 3 Zusammenfassung 4
15. 16 Tools 1. Docs as Code in einem Git- Repository verwalten 2. Automatischen Build- Prozess (Netlify, GitHub Pages, Vercel, …) (Optional: Previews für Pull- Requests) 3. Dokumentations-Website bereitstellen CC BY-NC-SA 4.0 | Dezember 2024 | Online-Dokumentation, die hilft | Alexander Schwartz Static Site Publishing name: Publishing Documentation Site on: push: branches: - main jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - name: Set up Node.js for Antora uses: actions/setup-node@v3 with: node-version: '16.x' cache: 'yarn' cache-dependency-path: 'antora/yarn.lock' - name: Build docs working-directory: antora run: ./build.sh - name: Upload artifact uses: actions/upload-pages-artifact@v2 with: path: antora/_site/keycloak-benchmark https://github.com/ahus1/keycloak-benchmark/blob/main/.github/workflows/docs-pages.yml
16. 17 Tools • Großer Funktionsumfang für technische Dokumentation • Seit über 15 Jahren verfügbar und weiterentwickelt • Standardisierung in 2020 bei der Eclipse Foundation begonnen CC BY-NC-SA 4.0 | Dezember 2024 | Online-Dokumentation, die hilft | Alexander Schwartz AsciiDoc®: Schreiben ohne Ablenkung mit einfachem Text Mehr dazu auf: • https://asciidoc.org/
17. CC BY-NC-SA 4.0 | Dezember 2024 | Online-Dokumentation, die hilft | Alexander Schwartz 18 Demo AsciiDoc Syntax und Ökosytem AsciiDoc: Texte und Listen Each sentence should be in a separate line. Every blank line creates a new paragraph. You can write *bold* text. _Italic_ works as well text. Lists . work . with . dots to make them numbered and * asterisks * to * make bullet points.
18. CC BY-NC-SA 4.0 | Dezember 2024 | Online-Dokumentation, die hilft | Alexander Schwartz 19 Demo AsciiDoc Syntax und Ökosytem AsciiDoc: Abschnitte und Auszeichnungen [IMPORTANT] -- You can mark a paragraph to be important. -- TIP: There is also the shorter one-line- syntax. ==== This is an example block. Use it to provide examples to your users. ==== ---- This is a listing. You can provide syntax highlighting for XML/Java etc. here. ----
19. CC BY-NC-SA 4.0 | Dezember 2024 | Online-Dokumentation, die hilft | Alexander Schwartz 20 Demo AsciiDoc Syntax und Ökosytem AsciiDoc: Tabellen Tables are blocks, `|===` marks their beginning and end. .Table title [cols="1,1,3a,1"] |=== |H1 |H2 |H3 |H4 |Cell 1 |Cell 2 |Formatting *of words* works like in _before_ if you switch the column or cell to AsciiDoc format. |Cell 4 |===
20. CC BY-NC-SA 4.0 | Dezember 2024 | Online-Dokumentation, die hilft | Alexander Schwartz 21 Demo AsciiDoc Syntax und Ökosytem AsciiDoc: Bilder Images can be in-line and as blocks. An image:file.svg[pdfwidth=3cm] image in- line. An image with a caption: .This is an image image::file.svg[] For schematic drawings prefer to use SVG images for best results on the Web and in PDFs.
21. CC BY-NC-SA 4.0 | Dezember 2024 | Online-Dokumentation, die hilft | Alexander Schwartz 22 Demo AsciiDoc Syntax und Ökosytem AsciiDoc: Grafiken am Beispiel PlantUML To store diagrams as text, have a look at PlantUML: .Diagrams can have a caption as well. plantuml::showcase_swimlanes.puml[swimlanes,svg] @startuml skinparam shadowing false |Component with Web-UI| start :User opens web page; :Forward to authentication; |#AntiqueWhite|Authentication| :Authenticate with user name\nand password; :Forward to Web-UI; |Component with Web-UI| :Open Web-UI; stop @enduml
22. CC BY-NC-SA 4.0 | Dezember 2024 | Online-Dokumentation, die hilft | Alexander Schwartz 23 Demo AsciiDoc Syntax und Ökosytem AsciiDoc: Quellcode-Beispiele einbinden .Standard include [source,java] ---- include::Example.java[] ---- :icons: font .Pick a block with callout [source,java,indent=0] ---- include::Example.java[tag=sop] ---- <1> this is your first line of Java
23. CC BY-NC-SA 4.0 | Dezember 2024 | Online-Dokumentation, die hilft | Alexander Schwartz 24 Demo AsciiDoc Syntax und Ökosytem Katas zum Selbststudium 1. Formatting of Texts 2. Using Lists 3. Using Tables 4. Images and Diagrams 5. Structuring a document 6. Adding Sourcecode examples https://github.com/ahus1/asciidoc-kata
24. • 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 | Dezember 2024 | Online-Dokumentation, die hilft | Alexander Schwartz 25 Schreiben in der IDE Demo AsciiDoc Syntax und Ökosytem List of editors: https://asciidoctor.org/docs/editing-asciidoc-with-live-preview/
25. CC BY-NC-SA 4.0 | Dezember 2024 | Online-Dokumentation, die hilft | Alexander Schwartz 26 Demo AsciiDoc Syntax und Ökosytem Validieren von Texten mit Vale # .vale.ini StylesPath = .github/styles MinAlertLevel = suggestion Packages = RedHat IgnoredClasses = error-message [*.adoc] BasedOnStyles = RedHat RedHat.TermsErrors = warning Mehr dazu auf: • https://github.com/errata-ai/vale-action
26. CC BY-NC-SA 4.0 | Dezember 2024 | Online-Dokumentation, die hilft | Alexander Schwartz 27 Demo AsciiDoc Syntax und Ökosytem Validieren in IntelliJ mit Grazie / Grazie Pro Mehr dazu auf: • https://intellij-asciidoc-plugin.ahus1.de/docs/users-guide/features/advanced/grammar-checking.html • Grammatik- und Spellchecker • Vale-Unterstützung • Gut integriert in das AsciiDoc Plugin für IntelliJ
27. • Online, automatisiert, aktuell • Durchsuchbar and themen-basiert • Navigation und Querverweise • Gruppiert nach Version und Komponente CC BY-NC-SA 4.0 | Dezember 2024 | Online-Dokumentation, die hilft | Alexander Schwartz 28 Dokumentation unterstützt die Nutzer bei ihrer Arbeit Warum AsciiDoc und Antora
28. CC BY-NC-SA 4.0 | Dezember 2024 | Online-Dokumentation, die hilft | Alexander Schwartz 29 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 … …
29. Git Repo CC BY-NC-SA 4.0 | Dezember 2024 | Online-Dokumentation, die hilft | Alexander Schwartz 30 Antora: Ablauf Was die Nutzer*innen 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
30. CC BY-NC-SA 4.0 | Dezember 2024 | Online-Dokumentation, die hilft | Alexander Schwartz Autor*in: 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*in: 1. Kopiert das bestehende UI-Theme (oder erstellt ein eigenes) 2. Legt UI-Anpassungen im Ordner supplemental_ui ab. 31 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/
31. CC BY-NC-SA 4.0 | Dezember 2024 | Online-Dokumentation, die hilft | Alexander Schwartz 32 Online-Dokumentation, die hilft Motivation 1 Dokumentation, die hilft 2 Werkzeuge 3 Zusammenfassung 4
32. CC BY-NC-SA 4.0 | Dezember 2024 | Online-Dokumentation, die hilft | Alexander Schwartz Motivation 33 Shift Left für Dokumentation • Jede*r im Entwicklungsprozess kann etwas beitragen Voraussetzung: • Wissen (Warum? Was? Wie?) → Every Page is Page One, Google Technical Writing • Strukturen (Vorlagen und Werkzeuge) → Topic Types, Antora, Styleguide • Prozesse (Automatisierung und Integration) → Vale, GitHub Actions, IDE-Plugins
33. AsciiDoc https://asciidoc.org Asciidoctor https://asciidoctor.org IntelliJ AsciiDoc Plugin https://ahus1.de/post/technical-writing-udemy Slides Links CC BY-NC-SA 4.0 | Dezember 2024 | Online-Dokumentation, die hilft | Alexander Schwartz 34 @ahus1de Documentation as Code mit Asciidoctor https://heise.de/-4642013 Antora https://antora.org/ https://www.ahus1.de/post/documentation-site-antora Video, Folien und Beispiele https://www.ahus1.de/post/asciidoctor-intro-and-deep-dive Softwaredokumentation: Tipps für mehr Freude und Effektivität https://www.heise.de/-9750682 @ahus1@fosstodon.org
34. Kontakt Alexander Schwartz Principal Software Engineer alexander.schwartz@gmx.net https://www.ahus1.de @ahus1de @ahus1@fosstodon.org CC BY-NC-SA 4.0 | Dezember 2024 | Online-Dokumentation, die hilft | Alexander Schwartz 35