Online-Dokumentation, die hilft

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

View Slide

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

Motivation
1
2
Werkzeuge
3
Zusammenfassung
4

View Slide

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

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

Motivation
1
2
Werkzeuge
3
Zusammenfassung
4

View Slide

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
Die hilfreiche Seite
1. Wiederkehrende Strukturen
2. Inhalte zum Überfliegen
3. Suche innerhalb der Website
4. Navigation

View Slide

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

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

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

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

Grundlagen Schreibstil für Online-Dokumentation
Google Technical Writing
https://developers.google.com/tech-writing/overview

View Slide

Motivation
1
2
Werkzeuge
3
Zusammenfassung
4

View Slide

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
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
Tools
• Großer Funktionsumfang für
technische Dokumentation
• Seit über 15 Jahren verfügbar und
weiterentwickelt
• Standardisierung in 2020 bei der
Eclipse Foundation begonnen
AsciiDoc®: Schreiben ohne Ablenkung mit einfachem Text
Mehr dazu auf:
• https://asciidoc.org/

View Slide

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

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

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

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

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

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

• Fokussiert bleiben und die Anwendung
nicht wechseln
• Zusammenarbeit über die
Versionsverwaltung
• IntelliJ AsciiDoc Plugin
bietet Unterstützung für Antora und
AsciiDoc
Schreiben in der IDE
List of editors:
https://asciidoctor.org/docs/editing-asciidoc-with-live-preview/

View Slide

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

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

• Online, automatisiert, aktuell
• Durchsuchbar and themen-basiert
• Navigation und Querverweise
• Gruppiert nach Version
und Komponente
Dokumentation unterstützt die Nutzer bei ihrer Arbeit
Warum AsciiDoc und Antora

View Slide

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

Git Repo
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

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

Motivation
1
2
Werkzeuge
3
Zusammenfassung
4

View Slide

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

AsciiDoc
https://asciidoc.org
Asciidoctor
https://asciidoctor.org
IntelliJ AsciiDoc Plugin
https://ahus1.de/post/technical-writing-udemy
Links
@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

Kontakt
Alexander Schwartz
Principal Software Engineer
[email protected]
https://www.ahus1.de
@ahus1de
@[email protected]

View Slide

Online-Dokumentation, die hilft

Online-Dokumentation, die hilft

Alexander Schwartz

More Decks by Alexander Schwartz

Other Decks in Programming

Featured

Transcript