Seminar Antora – Intensivseminar Gesamtprogramm für Dokumentationsplattformen

Beschreibung

Das fünftägige Intensivseminar fasst das vollständige Antora-Seminarportfolio in einem komprimierten End-to-End-Programm zusammen. Es verbindet Grundlagen, AsciiDoc, Content-Architektur, Ressourcen-IDs, Repository- und Versionsstrategien, Playbooks, UI, Suche, Erweiterungen, CI/CD, Betrieb, Sicherheit, Migration, Multi-Format-Publishing und Upgrade-Management. Die Themen werden in einer durchgängigen Referenzumgebung umgesetzt; Spezialgebiete werden auf entscheidungs- und arbeitsfähiges Niveau verdichtet, können aber die jeweilige mehrtägige Vertiefung nicht vollständig ersetzen.

Inhaltsübersicht

1. Zielarchitektur, Installation und erste Site
2. AsciiDoc und wiederverwendbare Inhalte
3. Komponenten, Module, Navigation und Xrefs
4. Repositories, Versionierung und Docs-as-Code-Governance
5. Playbook, Build-Profile und UI
6. Suche und Informationszugang
7. Antora- und Asciidoctor-Erweiterungen
8. CI/CD, Container und automatisierte Veröffentlichung
9. Betrieb, Sicherheit und Troubleshooting
10. Migration, Multi-Format-Ausgabe und Upgrade-Fahrplan

Lernziele

• Eine Antora-Plattform von der Inhaltsquelle bis zur Veröffentlichung ganzheitlich aufbauen.
• Content-, Repository-, UI-, Automatisierungs- und Betriebsentscheidungen aufeinander abstimmen.
• Qualität, Sicherheit, Migration und Upgrade als durchgängige Betriebsanforderungen integrieren.
• Für Spezialthemen belastbare Vertiefungs- und Umsetzungspläne ableiten.

1. Zielarchitektur, Installation und erste Site

Der erste Block verbindet Einsatzplanung, lokale Umgebung und einen lauffähigen Minimalbuild.

Schritt-für-Schritt: Eine Referenzarchitektur aufbauen und verifizieren

1. Anforderungen, Zielgruppen, Quellbestände und Veröffentlichungswege erfassen.
2. Repository-, Build- und Betriebsmodell für die Seminarumgebung festlegen.
3. Node.js-Projekt, Antora-Pakete und Verzeichnisstruktur reproduzierbar einrichten.
4. Eine minimale Komponente und ein Playbook anlegen.
5. Den ersten Build ausführen und Site, Protokoll sowie Artefakte kontrollieren.
6. Architekturannahmen, Versionen und offene Risiken dokumentieren.

Praxisaufgabe

Eine Referenzsite wird installiert und mit einem Architektur- und Versionsprotokoll abgenommen.

2. AsciiDoc und wiederverwendbare Inhalte

Seiten werden nach verständlichen Autorenregeln erstellt und durch Attribute, Partials, Beispiele und Anhänge ergänzt.

Schritt-für-Schritt: Eine belastbare Autorenvorlage umsetzen

1. Seitentyp, Zielgruppe, Voraussetzungen und erwartetes Ergebnis festlegen.
2. Überschriften, Listen, Tabellen, Codeblöcke und Hinweise semantisch strukturieren.
3. Attribute für wiederkehrende Produkt- und Versionsangaben definieren.
4. Wiederverwendbare Passagen als Partials auslagern und kontrolliert einbinden.
5. Bilder, Beispiele und Anhänge in den passenden Ressourcenfamilien ablegen.
6. Quelltext und gerenderte Seite mit einer Autoren-Checkliste prüfen.

Praxisaufgabe

Eine Installationsanleitung wird als wiederverwendbare, versionierbare AsciiDoc-Seite aufgebaut.

3. Komponenten, Module, Navigation und Xrefs

Die Inhaltsarchitektur wird für mehrere Produkte und Releases modelliert.

Schritt-für-Schritt: Ein skalierbares Content-Modell implementieren

1. Fachliche Grenzen in Komponenten, Versionen und Module übersetzen.
2. Komponenten-Deskriptoren und Ressourcenfamilien regelkonform anlegen.
3. Aufgabenorientierte Navigationsdateien erstellen und registrieren.
4. Lokale und modulübergreifende Querverweise mit stabilen Ressourcen-IDs setzen.
5. Komponenten- und versionsübergreifende Referenzen gezielt testen.
6. Struktur, Navigation und Referenzen mit Positiv- und Negativfällen validieren.

Praxisaufgabe

Zwei Komponenten mit mehreren Modulen werden verknüpft und als konsistente Navigation geprüft.

4. Repositories, Versionierung und Docs-as-Code-Governance

Verteilte Quellen werden mit einem geregelten Änderungs- und Releaseprozess verbunden.

Schritt-für-Schritt: Ein Multi-Repository-Arbeitsmodell etablieren

1. Repository-Zuschnitt, Branches, Tags und Startpfade definieren.
2. Quellen im Playbook mit kontrollierten Referenzmustern aggregieren.
3. Issue-, Branch-, Review- und Freigaberegeln für Dokumentationsänderungen festlegen.
4. Content Owner und Verantwortlichkeiten je Komponente zuordnen.
5. Releasebereitschaft und veröffentlichte Quellstände nachweisbar machen.
6. Rollback und Behandlung verspäteter Teilinhalte in einem Runbook dokumentieren.

Praxisaufgabe

Ein Release aus mehreren Repositories wird über einen dokumentierten Review- und Freigabeprozess vorbereitet.

5. Playbook, Build-Profile und UI

Konfiguration und Darstellung werden für lokale Entwicklung, Vorschau und Produktion getrennt steuerbar gemacht.

Schritt-für-Schritt: Playbook und UI für mehrere Umgebungen konfigurieren

1. Site-, Content-, AsciiDoc-, UI- und Ausgabeoptionen im Basis-Playbook ordnen.
2. Umgebungsspezifische Werte für Entwicklung, Staging und Produktion trennen.
3. UI-Bundle lokal entwickeln und zentrale Templates sowie Assets anpassen.
4. Header, Footer, Navigation und Seitenmetadaten auf die Zielorganisation abstimmen.
5. UI-Bundle bauen, versionieren und im Playbook fest referenzieren.
6. Mehrere Seiten- und Versionskonstellationen visuell sowie funktional abnehmen.

Praxisaufgabe

Ein gebrandetes UI-Bundle und drei kontrollierte Build-Profile werden in die Referenzsite integriert.

6. Suche und Informationszugang

Die statische Site erhält einen kontrollierten Suchindex und nachvollziehbare Relevanzregeln.

Schritt-für-Schritt: Lunr-Suche integrieren und prüfen

1. Indexumfang, Sprachen, Ausschlüsse und Metadatenfelder festlegen.
2. Sucherweiterung und UI-Komponenten im Build registrieren.
3. Index über mehrere Komponenten und Versionen erzeugen.
4. Suchoberfläche, Tastaturbedienung und Ergebnisdarstellung testen.
5. Relevanz mit repräsentativen Suchfällen bewerten und nachschärfen.
6. Indexgröße, Build-Zeit und Browserlaufzeit messen und dokumentieren.

Praxisaufgabe

Ein Suchtestkatalog wird ausgeführt und die Indexkonfiguration anhand der Ergebnisse angepasst.

7. Antora- und Asciidoctor-Erweiterungen

Zwei Erweiterungswege werden anhand kleiner, klar abgegrenzter Beispiele eingeordnet.

Schritt-für-Schritt: Validierung und benutzerdefinierte Makros prototypisch umsetzen

1. Anwendungsfall entweder der AsciiDoc-Verarbeitung oder dem Antora-Generator zuordnen.
2. Eine kleine Asciidoctor-Erweiterung für eine domänenspezifische Auszeichnung registrieren.
3. Eine Antora-Erweiterung für Ressourcenvalidierung am geeigneten Ereignis anbinden.
4. Konfiguration, Fehlermeldungen und sichere Standardwerte ergänzen.
5. Erfolgs-, Fehler- und Grenzfälle automatisiert testen.
6. Produktionsanforderungen und Bedarf für Vertiefungsseminare dokumentieren.

Praxisaufgabe

Ein Makro und ein Content-Validator werden prototypisch erstellt und in den Referenzbuild eingebunden.

8. CI/CD, Container und automatisierte Veröffentlichung

Der lokale Build wird in eine reproduzierbare, gestufte Pipeline überführt.

Schritt-für-Schritt: Eine produktionsnahe Build- und Deployment-Pipeline erstellen

1. Abhängigkeiten sperren und einen reproduzierbaren Installationsschritt definieren.
2. Build in einem versionierten Container oder einer kontrollierten CI-Laufzeit ausführen.
3. Linting, Tests, Antora-Build und Artefaktprüfung als getrennte Stufen anlegen.
4. Vorschau für Änderungen und Staging für freigegebene Builds bereitstellen.
5. Produktivveröffentlichung mit Freigabe, atomarem Wechsel und Rollback absichern.
6. Build-Protokoll, Quellmanifest und aufbewahrte Artefakte als Nachweis sichern.

Praxisaufgabe

Die Referenzsite wird über eine Pipeline gebaut, geprüft, bereitgestellt und kontrolliert zurückgerollt.

9. Betrieb, Sicherheit und Troubleshooting

Betriebsfähigkeit umfasst Zugangsdaten, Lieferkette, Performance, Monitoring und einen reproduzierbaren Diagnoseprozess.

Schritt-für-Schritt: Ein Betriebs- und Sicherheitsbaseline etablieren

1. Private Quellen mit minimal berechtigten, rotierbaren Zugangsdaten anbinden.
2. Abhängigkeiten, Container und Build-Artefakte auf Lieferkettenrisiken prüfen.
3. Build-Zeit, Speicherverbrauch, Quellabrufe und Ausgabegröße messen.
4. Protokolle und Kennzahlen mit Schwellenwerten für Warnung und Fehler versehen.
5. Fehler nach Quelle, Konfiguration, Inhalt, Erweiterung, UI oder Veröffentlichung isolieren.
6. Backup, Wiederanlauf, Incident- und Rollback-Schritte in einem Runbook festhalten.

Praxisaufgabe

Ein kombinierter Security- und Betriebscheck wird durchgeführt und ein vorbereiteter Build-Ausfall behoben.

10. Migration, Multi-Format-Ausgabe und Upgrade-Fahrplan

Zum Abschluss werden Bestandsübernahme, zusätzliche Publikationsformate und kontrollierte Weiterentwicklung geplant.

Schritt-für-Schritt: Von der Pilotplattform zum nachhaltigen Betrieb überführen

1. Bestehende Inhalte, Links, Assets und URL-Anforderungen inventarisieren.
2. Migrationswellen mit Konvertierung, Redirects, Abnahme und Rückfalloption planen.
3. Eine Assembly-Navigation für PDF, EPUB oder eigenständiges HTML vorbereiten.
4. Einen Beispiel-Export erzeugen und Inhalt, Reihenfolge, Assets sowie Metadaten prüfen.
5. Abhängigkeiten und Erweiterungen für ein zukünftiges Upgrade inventarisieren.
6. Pilot-, Migrations-, Vertiefungs- und Upgrade-Arbeitspakete in einen priorisierten Fahrplan überführen.

Praxisaufgabe

Als Abschluss entsteht ein abgestimmter Umsetzungsfahrplan für Migration, Mehrformatausgabe, Betrieb und Weiterqualifizierung.

Zielgruppe und Voraussetzungen

Zielgruppe: Interdisziplinäre Einführungsteams aus technischer Redaktion, Documentation Engineering, Entwicklung, DevOps, Plattformbetrieb, Architektur, Informationssicherheit und Projektleitung.

Voraussetzungen: Grundkenntnisse in Git, Kommandozeile und technischer Dokumentation; JavaScript-Kenntnisse sind für die Erweiterungsübungen hilfreich.

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.