Tweet
Tweet

Slide 1

Slide 1 text

Online-Dokumentation, die hilft: Strukturen, Prozesse, Tools Alexander Schwartz, Principal Software Engineer @ Red Hat IT-Tage Frankfurt | 2024-12-10

Slide 2

Slide 2 text

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

Slide 3

Slide 3 text

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

Slide 4

Slide 4 text

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

Slide 5

Slide 5 text

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)

Slide 6

Slide 6 text

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

Slide 7

Slide 7 text

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“.

Slide 8

Slide 8 text

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

Slide 9

Slide 9 text

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/

Slide 10

Slide 10 text

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

Slide 11

Slide 11 text

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

Slide 12

Slide 12 text

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:

Slide 13

Slide 13 text

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

Slide 14

Slide 14 text

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

Slide 15

Slide 15 text

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

Slide 16

Slide 16 text

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/

Slide 17

Slide 17 text

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.

Slide 18

Slide 18 text

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

Slide 19

Slide 19 text

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

Slide 20

Slide 20 text

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.

Slide 21

Slide 21 text

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

Slide 22

Slide 22 text

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

Slide 23

Slide 23 text

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

Slide 24

Slide 24 text

• 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/

Slide 25

Slide 25 text

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

Slide 26

Slide 26 text

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

Slide 27

Slide 27 text

• 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

Slide 28

Slide 28 text

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

Slide 29

Slide 29 text

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

Slide 30

Slide 30 text

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/

Slide 31

Slide 31 text

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

Slide 32

Slide 32 text

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

Slide 33

Slide 33 text

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

Slide 34

Slide 34 text

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