$30 off During Our Annual Pro Sale. View Details »

Online-Dokumentation, die hilft

Online-Dokumentation, die hilft

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.

Alexander Schwartz

September 29, 2023
Tweet

More Decks by Alexander Schwartz

Other Decks in Programming

Transcript

  1. Online-Dokumentation, die hilft:
    Strukturen, Prozesse, Tools
    Alexander Schwartz, Principal Software Engineer @ Red Hat
    BedCon Berlin| 2023-09-29

    View Slide

  2. CC BY-NC-SA 4.0 | September 2023 | Online-Dokumentation die hilft | Alexander Schwartz 2
    Online-Dokumentation die hilft
    Motivation
    1
    Dokumentation, die hilft
    2
    Werkzeuge
    3
    Zusammenfassung
    4

    View Slide

  3. CC BY-NC-SA 4.0 | September 2023 | Online-Dokumentation die hilft | Alexander Schwartz 3
    Online-Dokumentation die hilft
    Motivation
    1
    Dokumentation, die hilft
    2
    Werkzeuge
    3
    Zusammenfassung
    4

    View Slide

  4. CC BY-NC-SA 4.0 | September 2023 | 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

    View Slide

  5. CC BY-NC-SA 4.0 | September 2023 | 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)

    View Slide

  6. CC BY-NC-SA 4.0 | September 2023 | Online-Dokumentation die hilft | Alexander Schwartz 6
    Online-Dokumentation die hilft
    Motivation
    1
    Dokumentation, die hilft
    2
    Werkzeuge
    3
    Zusammenfassung
    4

    View Slide

  7. CC BY-NC-SA 4.0 | September 2023 | 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“

    View Slide

  8. CC BY-NC-SA 4.0 | September 2023 | Online-Dokumentation die hilft | Alexander Schwartz
    Dokumentation die hilft
    8
    Die hilfreiche Seite
    1. Wiederkehrende Strukturen
    2. Inhalte zum Überfliegen
    3. Suche innerhalb der Website
    4. Navigation

    View Slide

  9. CC BY-NC-SA 4.0 | September 2023 | 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/

    View Slide

  10. CC BY-NC-SA 4.0 | September 2023 | Online-Dokumentation die hilft | Alexander Schwartz 10
    Dokumentation die hilft
    Hierarchie (top → down)
    Den Einstieg erleichtern 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

    View Slide

  11. CC BY-NC-SA 4.0 | September 2023 | 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

    View Slide

  12. CC BY-NC-SA 4.0 | September 2023 | 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:

    View Slide

  13. CC BY-NC-SA 4.0 | September 2023 | 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

    View Slide

  14. CC BY-NC-SA 4.0 | September 2023 | Online-Dokumentation die hilft | Alexander Schwartz 14
    Online-Dokumentation die hilft
    Motivation
    1
    Dokumentation, die hilft
    2
    Werkzeuge
    3
    Zusammenfassung
    4

    View Slide

  15. 15
    Tools
    1. 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 2023 | 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

    View Slide

  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 2023 | Online-Dokumentation die hilft | Alexander Schwartz
    AsciiDoc®: Schreiben ohne Ablenkung mit einfachem Text
    Mehr dazu auf:
    • https://asciidoc.org/

    View Slide

  17. CC BY-NC-SA 4.0 | September 2023 | 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.

    View Slide

  18. CC BY-NC-SA 4.0 | September 2023 | 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.
    ----

    View Slide

  19. CC BY-NC-SA 4.0 | September 2023 | 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
    |===

    View Slide

  20. CC BY-NC-SA 4.0 | September 2023 | 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.

    View Slide

  21. CC BY-NC-SA 4.0 | September 2023 | 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

    View Slide

  22. CC BY-NC-SA 4.0 | September 2023 | 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

    View Slide

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

    View Slide

  24. CC BY-NC-SA 4.0 | September 2023 | 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

    View Slide

  25. CC BY-NC-SA 4.0 | September 2023 | 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

    View Slide

  26. • Online, automatisiert, aktuell
    • Durchsuchbar and themen-basiert
    • Navigation und Querverweise
    • Gruppiert nach Version
    und Komponente
    CC BY-NC-SA 4.0 | September 2023 | Online-Dokumentation die hilft | Alexander Schwartz 26
    Dokumentation unterstützt die Nutzer bei ihrer Arbeit
    Warum AsciiDoc und Antora

    View Slide

  27. CC BY-NC-SA 4.0 | September 2023 | 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
    … …

    View Slide

  28. Git Repo
    CC BY-NC-SA 4.0 | September 2023 | 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

    View Slide

  29. CC BY-NC-SA 4.0 | September 2023 | Online-Dokumentation die hilft | 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.
    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/

    View Slide

  30. CC BY-NC-SA 4.0 | September 2023 | Online-Dokumentation die hilft | Alexander Schwartz 30
    Online-Dokumentation die hilft
    Motivation
    1
    Dokumentation, die hilft
    2
    Werkzeuge
    3
    Zusammenfassung
    4

    View Slide

  31. CC BY-NC-SA 4.0 | September 2023 | 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

    View Slide

  32. AsciiDoc
    https://asciidoc.org
    Asciidoctor
    https://asciidoctor.org
    IntelliJ AsciiDoc Plugin
    https://ahus1.de/post/technical-writing-udemy
    Links
    CC BY-NC-SA 4.0 | September 2023 | Online-Dokumentation die hilft | Alexander Schwartz 32
    @ahus1de
    Asciidoctor Web PDF
    https://github.com/ggrossetie/asciidoctor-web-pdf
    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
    @[email protected]

    View Slide

  33. Kontakt
    Alexander Schwartz
    Principal Software Engineer
    [email protected]
    https://www.ahus1.de
    @ahus1de
    @[email protected]
    CC BY-NC-SA 4.0 | September 2023 | Online-Dokumentation die hilft | Alexander Schwartz 33

    View Slide