Seminar Antora – Kompaktseminar Dokumentationsplattformen in der Praxis

Beschreibung

Das dreitägige Kompaktseminar vermittelt die wesentlichen Antora-Kompetenzen für einen schnellen, kontrollierten Projektstart. Eine vollständige Site wird mit AsciiDoc-Inhalten, Komponenten und Modulen, Playbook, Navigation, UI-Anpassung, Suche, CI-Build und grundlegender Betriebsübergabe aufgebaut. Spezialthemen wie komplexe Erweiterungsentwicklung oder umfangreiche Migration werden eingeordnet und in einen Folgeplan überführt.

Inhaltsübersicht

1. Projektziel, Architektur und Installation
2. AsciiDoc und Content-Struktur
3. Playbook, Navigation und Xrefs
4. UI, Branding und Informationszugang
5. CI-Build und Vorschau
6. Betriebsübergabe und Sicherheit
7. Ausbau- und Qualifizierungsfahrplan

Lernziele

• Eine vollständige Antora-Pilotumgebung in kurzer Zeit aufbauen.
• Inhalte, Navigation, UI und Suche zu einer nutzbaren Site verbinden.
• Den Build in eine einfache, reproduzierbare CI-Pipeline überführen.
• Betriebsrisiken und notwendige Vertiefungen in einem Projektfahrplan festhalten.

1. Projektziel, Architektur und Installation

Das Pilotvorhaben wird abgegrenzt und die Arbeitsumgebung reproduzierbar eingerichtet.

Schritt-für-Schritt: Einen kontrollierten Pilotstart vorbereiten

1. Zielgruppen, Pilotinhalt, Repositories und Abnahmekriterien festlegen.
2. Repository-, Build- und Veröffentlichungsmodell als Kontextdiagramm dokumentieren.
3. Node.js-Projekt und Antora-Pakete projektbezogen installieren.
4. Verzeichnisstruktur für Inhalt, Playbook, UI und Ausgabe anlegen.
5. Versionen und Installationsstatus mit einem Prüfskript kontrollieren.
6. Pilotrisiken und nicht enthaltene Spezialthemen ausdrücklich dokumentieren.

Praxisaufgabe

Ein abgestimmter Pilotsteckbrief und eine verifizierte Arbeitsumgebung werden erstellt.

2. AsciiDoc und Content-Struktur

Aus einem kleinen Inhaltsbestand entsteht eine regelkonforme Komponente mit wiederverwendbaren Ressourcen.

Schritt-für-Schritt: Pilotinhalte strukturieren und schreiben

1. Komponente, Version und Module für den Pilotumfang festlegen.
2. Komponenten-Deskriptor und Familienverzeichnisse anlegen.
3. Start-, Aufgaben- und Referenzseite nach einer einheitlichen Vorlage erstellen.
4. Bilder, Beispiele und Partials in geeigneten Ressourcenfamilien ablegen.
5. Attribute und Benennungsregeln für wiederkehrende Angaben definieren.
6. Quellen mit Autoren- und Strukturcheckliste prüfen.

Praxisaufgabe

Ein repräsentativer Inhaltsbereich wird vollständig in Antora-Struktur überführt.

3. Playbook, Navigation und Xrefs

Das Playbook aggregiert die Quelle und erzeugt aus Navigation sowie Referenzen eine zusammenhängende Site.

Schritt-für-Schritt: Den ersten vollständigen Site-Build konfigurieren

1. Site-Metadaten, Ausgabeziel und Content-Quelle im Playbook eintragen.
2. Navigation auf Basis der wichtigsten Nutzeraufgaben erstellen.
3. Lokale und modulübergreifende Xrefs mit stabilen Ressourcen-IDs setzen.
4. Default UI konfigurieren und den ersten Build ausführen.
5. Build-Protokoll, Navigation, Referenzen und Assets systematisch prüfen.
6. Fehlerhafte Quelle, YAML-Einrückung und Referenz anhand vorbereiteter Fälle korrigieren.

Praxisaufgabe

Die Pilotkomponente wird als navigierbare Site gebaut und mit einem Abnahmeprotokoll geprüft.

4. UI, Branding und Informationszugang

Die Site erhält ein minimales Organisationsbranding und eine nutzbare Suchfunktion.

Schritt-für-Schritt: Darstellung und Suche für den Pilot anpassen

1. UI-Entwicklungsumgebung und eigenes UI-Projekt vorbereiten.
2. Logo, Typografie, zentrale Farben und Footer-Inhalte über definierte Assets und Templates anpassen.
3. Header und Seitenelemente auf Zugänglichkeit und responsive Darstellung prüfen.
4. Lunr-Suche registrieren und Indexumfang festlegen.
5. Repräsentative Suchfälle ausführen und Ergebnisdarstellung bewerten.
6. UI-Bundle versionieren und im Playbook fest referenzieren.

Praxisaufgabe

Ein gebrandetes UI-Bundle mit funktionierender Suche wird erstellt und auf mehreren Seitentypen geprüft.

5. CI-Build und Vorschau

Der lokale Build wird automatisiert, damit Änderungen früh geprüft und reproduzierbar bereitgestellt werden.

Schritt-für-Schritt: Eine kompakte CI-Pipeline einrichten

1. Installations- und Build-Befehle als projektbezogene Skripte definieren.
2. Abhängigkeiten sperren und Cache nur für wiederherstellbare Dateien verwenden.
3. Syntaxprüfung, Antora-Build und Artefaktprüfung als Pipeline-Schritte einrichten.
4. Für Änderungsbranches eine temporäre Vorschau erzeugen.
5. Build-Protokoll und Site-Artefakt für die Fehleranalyse aufbewahren.
6. Einen fehlgeschlagenen Lauf beheben und anschließend erfolgreich wiederholen.

Praxisaufgabe

Die Pilot-Site wird aus einem frischen CI-Lauf gebaut und als prüfbare Vorschau bereitgestellt.

6. Betriebsübergabe und Sicherheit

Auch ein Pilot benötigt klare Verantwortlichkeiten, Zugangsschutz und Wiederanlaufregeln.

Schritt-für-Schritt: Einen minimalen Betriebsstandard festlegen

1. Verantwortliche für Inhalte, Plattform, UI, Freigabe und Incident-Bearbeitung benennen.
2. Private Quellen und Zugangsdaten nach dem Prinzip minimaler Rechte absichern.
3. Build-Zeit, Fehlerquote und Ausgabegröße als erste Betriebskennzahlen erfassen.
4. Backup- und Wiederanlaufbedarf für Konfiguration, UI und veröffentlichte Artefakte festlegen.
5. Fehlerklassifikation und Eskalationsweg in einem kurzen Runbook dokumentieren.
6. Betriebsübergabe anhand einer Checkliste fachlich und technisch abnehmen.

Praxisaufgabe

Ein Pilot-Betriebshandbuch mit Rollen, Zugangsschutz, Kennzahlen und Wiederanlauf entsteht.

7. Ausbau- und Qualifizierungsfahrplan

Zum Abschluss werden Pilotbefunde in priorisierte Arbeitspakete und passende Vertiefungen überführt.

Schritt-für-Schritt: Den Übergang vom Pilot zum Regelbetrieb planen

1. Erfüllte und offene Abnahmekriterien des Piloten bewerten.
2. Lücken bei Content-Modell, UI, Suche, Automatisierung, Sicherheit und Betrieb priorisieren.
3. Migrationsvolumen und notwendige Redirect- oder Konvertierungsarbeiten grob schätzen.
4. Bedarf für Erweiterungen, Multi-Format-Ausgabe und komplexe Versionierung einordnen.
5. Passende Vertiefungsseminare nach Rollen und Projektphase zuordnen.
6. Einen 30-, 60- und 90-Tage-Fahrplan mit Verantwortlichen und Entscheidungspunkten erstellen.

Praxisaufgabe

Als Arbeitsergebnis wird ein abgestimmter Ausbauplan für die Antora-Plattform erstellt.

Zielgruppe und Voraussetzungen

Zielgruppe: Projektteams aus technischer Redaktion, Entwicklung, DevOps, Plattformbetrieb und technischer Projektleitung, die in kurzer Zeit eine belastbare Antora-Pilotumgebung aufbauen möchten.

Voraussetzungen: Grundkenntnisse in Git, Kommandozeile und technischer Dokumentation; Programmierkenntnisse sind nicht zwingend erforderlich.

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.