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 betterCode(ArchDoc) | 2024-09-30
2. CC BY-NC-SA 4.0 | September 2024 | Online-Dokumentation, die hilft | Alexander Schwartz 2 Online-Dokumentation, die hilft Motivation 1 Dokumentation, die hilft 2 Werkzeuge 3 Zusammenfassung 4
3. CC BY-NC-SA 4.0 | September 2024 | Online-Dokumentation, die hilft | Alexander Schwartz 3 Online-Dokumentation, die hilft Motivation 1 Dokumentation, die hilft 2 Werkzeuge 3 Zusammenfassung 4
4. CC BY-NC-SA 4.0 | September 2024 | Online-Dokumentation, die hilft | Alexander Schwartz Motivation 4 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 | September 2024 | Online-Dokumentation, die hilft | Alexander Schwartz Motivation 5 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 | September 2024 | Online-Dokumentation, die hilft | Alexander Schwartz 6 Online-Dokumentation, die hilft Motivation 1 Dokumentation, die hilft 2 Werkzeuge 3 Zusammenfassung 4
7. CC BY-NC-SA 4.0 | September 2024 | Online-Dokumentation, die hilft | Alexander Schwartz Dokumentation die hilft 7 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 | September 2024 | Online-Dokumentation, die hilft | Alexander Schwartz Dokumentation die hilft 8 Die hilfreiche Site 1. Wiederkehrende Strukturen 2. Inhalte zum Überfliegen 3. Suche innerhalb der Website 4. Navigation
9. CC BY-NC-SA 4.0 | September 2024 | Online-Dokumentation, die hilft | Alexander Schwartz Dokumentation die hilft 9 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 | September 2024 | Online-Dokumentation, die hilft | Alexander Schwartz 10 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 | September 2024 | Online-Dokumentation, die hilft | Alexander Schwartz 11 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 | September 2024 | Online-Dokumentation, die hilft | Alexander Schwartz 12 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 | September 2024 | Online-Dokumentation, die hilft | Alexander Schwartz 13 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 | September 2024 | Online-Dokumentation, die hilft | Alexander Schwartz 14 Online-Dokumentation, die hilft Motivation 1 Dokumentation, die hilft 2 Werkzeuge 3 Zusammenfassung 4
15. 15 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 | September 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. 16 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 | September 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 | September 2024 | Online-Dokumentation, die hilft | Alexander Schwartz 17 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 | September 2024 | Online-Dokumentation, die hilft | Alexander Schwartz 18 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 | September 2024 | Online-Dokumentation, die hilft | Alexander Schwartz 19 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 | September 2024 | Online-Dokumentation, die hilft | Alexander Schwartz 20 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 | September 2024 | Online-Dokumentation, die hilft | Alexander Schwartz 21 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 | September 2024 | Online-Dokumentation, die hilft | Alexander Schwartz 22 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. • 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 | September 2024 | Online-Dokumentation, die hilft | Alexander Schwartz 23 Schreiben in der IDE Demo AsciiDoc Syntax und Ökosytem List of editors: https://asciidoctor.org/docs/editing-asciidoc-with-live-preview/
24. CC BY-NC-SA 4.0 | September 2024 | Online-Dokumentation, die hilft | Alexander Schwartz 24 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
25. CC BY-NC-SA 4.0 | September 2024 | Online-Dokumentation, die hilft | Alexander Schwartz 25 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
26. • Online, automatisiert, aktuell • Durchsuchbar and themen-basiert • Navigation und Querverweise • Gruppiert nach Version und Komponente CC BY-NC-SA 4.0 | September 2024 | Online-Dokumentation, die hilft | Alexander Schwartz 26 Dokumentation unterstützt die Nutzer bei ihrer Arbeit Warum AsciiDoc und Antora
27. CC BY-NC-SA 4.0 | September 2024 | Online-Dokumentation, die hilft | Alexander Schwartz 27 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 … …
28. Git Repo CC BY-NC-SA 4.0 | September 2024 | Online-Dokumentation, die hilft | Alexander Schwartz 28 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
29. CC BY-NC-SA 4.0 | September 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. 29 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/
30. CC BY-NC-SA 4.0 | September 2024 | Online-Dokumentation, die hilft | Alexander Schwartz 30 Online-Dokumentation, die hilft Motivation 1 Dokumentation, die hilft 2 Werkzeuge 3 Zusammenfassung 4
31. CC BY-NC-SA 4.0 | September 2024 | Online-Dokumentation, die hilft | Alexander Schwartz Motivation 31 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
32. 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 | September 2024 | Online-Dokumentation, die hilft | Alexander Schwartz 32 @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 @ahus1@fosstodon.org
33. Kontakt Alexander Schwartz Principal Software Engineer alexander.schwartz@gmx.net https://www.ahus1.de @ahus1de @ahus1@fosstodon.org CC BY-NC-SA 4.0 | September 2024 | Online-Dokumentation, die hilft | Alexander Schwartz 33