Seminar Antora – AsciiDoc für technische Dokumentation

Beschreibung

Das Seminar vermittelt AsciiDoc als strukturierte Auszeichnungssprache für Inhalte, die in einer Antora-Site verarbeitet werden. Behandelt werden Dokumentaufbau, Überschriften, Listen, Tabellen, Quellcode, Abbildungen, Attribute, bedingte Inhalte, Includes und wiederverwendbare Partials. Durchgängige Übungen führen von einer Rohdatei zu modularen, wartbaren und validierbaren Seiten.

Inhaltsübersicht

1. Dokumentstruktur und semantische Gliederung
2. Listen, Beschreibungen und Tabellen
3. Quellcode, Konsolenausgaben und Abbildungen
4. Hinweise, Attribute und bedingte Inhalte
5. Includes, Partials und Wiederverwendung
6. Autorenqualität und redaktionelle Konventionen

Lernziele

• Technische Inhalte semantisch strukturiert in AsciiDoc verfassen.
• Medien, Quellcode, Tabellen, Hinweise und interne Verweise korrekt einsetzen.
• Attribute, Includes und Partials für kontrollierte Wiederverwendung nutzen.
• Autorenregeln und Prüfschritte für wartbare Inhalte anwenden.

1. Dokumentstruktur und semantische Gliederung

Eine belastbare Seite beginnt mit eindeutiger Dokumentstruktur, konsistenten Abschnittsebenen und sinnvoller semantischer Auszeichnung.

Schritt-für-Schritt: Eine neue technische Seite aufbauen

1. Eine neue Datei im vorgesehenen Seitenverzeichnis anlegen und einen eindeutigen Dokumenttitel setzen.
2. Abschnittsebenen nach Informationshierarchie statt nach visueller Wirkung strukturieren.
3. Absätze, Hervorhebungen, Monospace-Auszeichnung und Sonderzeichen semantisch korrekt einsetzen.
4. Dokumentattribute nur dort definieren, wo ihr Geltungsbereich bewusst gewählt ist.
5. Die Seite lokal konvertieren und Warnungen zu Struktur oder Syntax unmittelbar beheben.

Praxisaufgabe

Eine unstrukturierte Installationsnotiz wird in eine klar gegliederte technische Seite überführt.

2. Listen, Beschreibungen und Tabellen

Listen und Tabellen werden so eingesetzt, dass Abläufe, Optionen und Vergleichsdaten auch bei späterer Pflege verständlich bleiben.

Schritt-für-Schritt: Komplexe Informationen übersichtlich darstellen

1. Aufzählungen für gleichrangige Informationen und nummerierte Listen für zwingende Reihenfolgen auswählen.
2. Verschachtelungen mit konsistenter Einrückung und eindeutigen Fortsetzungszeichen aufbauen.
3. Beschreibungslisten für Begriffe, Parameter und Zustände verwenden.
4. Tabellen mit Spaltenformaten, Kopfzeilen und geeigneten Breiten definieren.
5. Tabelleninhalte auf mobile Lesbarkeit und alternative Darstellungsformen prüfen.

Praxisaufgabe

Parameter, Standardwerte und Auswirkungen einer Beispielkonfiguration werden als wartbare Tabelle dokumentiert.

3. Quellcode, Konsolenausgaben und Abbildungen

Technische Beispiele benötigen klare Grenzen zwischen Eingaben, Ausgaben, Dateiinhalten und erklärendem Text.

Schritt-für-Schritt: Ein reproduzierbares technisches Beispiel dokumentieren

1. Quellcodeblock, Konsolenblock und Konfigurationsdatei anhand des Informationszwecks unterscheiden.
2. Syntaxhervorhebung und Blocktitel setzen, ohne den Codeinhalt semantisch zu verfälschen.
3. Lange Zeilen, Platzhalter, Auslassungen und sensible Werte nachvollziehbar kennzeichnen.
4. Abbildungen im vorgesehenen Ressourcenverzeichnis ablegen und mit Alternativtext versehen.
5. Text, Code und Abbildung in eine überprüfbare Schrittfolge mit erwarteten Ergebnissen einbetten.

Praxisaufgabe

Ein Installationsvorgang wird mit Befehlen, erwarteter Ausgabe, Konfigurationsausschnitt und Prüfbild dokumentiert.

4. Hinweise, Attribute und bedingte Inhalte

Attribute und Bedingungen erlauben kontrollierte Varianten, können aber bei unklaren Geltungsbereichen zu schwer prüfbaren Inhalten führen.

Schritt-für-Schritt: Varianten kontrolliert modellieren

1. Wiederkehrende Werte als Attribute identifizieren und geeignete Namen festlegen.
2. Globale, komponentenbezogene und seitenbezogene Attribute nach Zuständigkeit zuordnen.
3. Hinweisblöcke nach tatsächlicher Bedeutung statt als rein visuelle Hervorhebung auswählen.
4. Bedingte Abschnitte mit eindeutigem Anwendungsfall und begrenzter Verschachtelung erstellen.
5. Mindestens zwei Attributvarianten bauen und beide Ausgaben auf Vollständigkeit prüfen.

Praxisaufgabe

Eine Installationsseite wird für zwei Produkteditionen parametrisiert und auf widerspruchsfreie Ausgabe getestet.

5. Includes, Partials und Wiederverwendung

Wiederverwendung reduziert Doppelpflege, erfordert jedoch klare Schnittstellen, stabile Attribute und nachvollziehbare Besitzverhältnisse.

Schritt-für-Schritt: Gemeinsame Inhalte modularisieren

1. Doppelte Textteile identifizieren und zwischen eigenständiger Seite, Partial und Beispielressource unterscheiden.
2. Ein Partial mit eindeutigem Zweck und dokumentierten Eingabeattributen erstellen.
3. Das Partial aus mehreren Seiten über Antora-Ressourcen-IDs einbinden.
4. Überschriften, Anker und relative Bezüge so gestalten, dass der eingebundene Inhalt kontextunabhängig bleibt.
5. Änderungsauswirkungen durch einen Test-Build aller verwendenden Seiten kontrollieren.

Praxisaufgabe

Ein gemeinsam genutzter Sicherheitshinweis wird als Partial modelliert, parametrisiert und in mehreren Modulen verwendet.

6. Autorenqualität und redaktionelle Konventionen

Abschließend werden technische und redaktionelle Regeln zu einem wiederholbaren Prüfablauf verbunden.

Schritt-für-Schritt: Eine Seite freigabefähig prüfen

1. Dateiname, Dokumenttitel, Abschnittsebenen und Navigationseintrag auf Konsistenz prüfen.
2. Begriffe, Anredeform, Schreibweisen und Codeformat anhand eines Styleguides kontrollieren.
3. Alle Verweise, Includes, Bilder und Downloads in einem vollständigen Site-Build validieren.
4. Warnungen nach Ursache klassifizieren und nicht durch pauschale Unterdrückung verdecken.
5. Eine Peer-Review-Checkliste anwenden und Korrekturen in einem getrennten Commit dokumentieren.
6. Die Seite anhand definierter Abnahmekriterien für die Veröffentlichung freigeben.

Praxisaufgabe

Eine vorbereitete Seite mit Syntax-, Struktur- und Wiederverwendungsfehlern wird systematisch korrigiert und abgenommen.

Zielgruppe und Voraussetzungen

Zielgruppe: Technische Redaktionen, Software- und Systemdokumentation, Entwicklerinnen und Entwickler, Content Engineering, Support-Dokumentation und fachliche Beitragende.

Voraussetzungen: Sicherer Umgang mit Texteditor und Dateisystem; Git-Grundkenntnisse sind hilfreich, Markup-Vorkenntnisse werden nicht vorausgesetzt.

Methodik und Arbeitsweise

Die Inhalte werden durch strukturierte Erläuterungen, Demonstrationen, schrittweise Konfigurations- und Analyseaufgaben sowie kontrollierte Fehlerfälle vertieft. Jede Übung verwendet definierte Ausgangswerte, Prüfpunkte und Dokumentationsanforderungen, damit die erarbeiteten Abläufe im späteren Projekt- und Betriebsalltag reproduzierbar bleiben.