Seminar Antora – Architektur und Einsatzplanung

Beschreibung

Das Seminar ordnet Antora als Dokumentationsplattform ein und überführt fachliche, technische und organisatorische Anforderungen in eine belastbare Zielarchitektur. Im Mittelpunkt stehen die Dokumentationspipeline, Git-basierte Inhaltsquellen, Verantwortungsgrenzen, Betriebsmodelle und ein schrittweise ausführbarer Einführungsplan. Die Inhalte sind auf Architektur- und Entscheidungsaufgaben ausgerichtet; eine vollständige Implementierung ist nicht Gegenstand des Formats.

Inhaltsübersicht

1. Einsatzfelder und Systemgrenzen
2. Dokumentationspipeline und Artefakte
3. Zielarchitektur und Betriebsmodell
4. Pilotierung und Einführungsfahrplan

Lernziele

• Antora fachlich und technisch gegenüber alternativen Publikationsansätzen einordnen.
• Komponenten, Datenflüsse und Verantwortungsgrenzen einer Zielarchitektur beschreiben.
• Betriebs-, Sicherheits- und Governance-Anforderungen strukturiert bewerten.
• Einen realistischen Pilot- und Einführungsfahrplan mit Abnahmekriterien formulieren.

1. Einsatzfelder und Systemgrenzen

Zu Beginn wird geklärt, welche Dokumentationsprobleme mit einer Git-basierten statischen Pipeline gelöst werden und welche Aufgaben außerhalb des Systems verbleiben.

Schritt-für-Schritt: Anforderungen erfassen und Einsatzgrenzen bestimmen

1. Dokumentationsarten, Zielgruppen, Sprachen, Versionsstände und Veröffentlichungskanäle erfassen.
2. Bestehende Autorenwerkzeuge, Quellformate, Freigaben und Bereitstellungswege als Ist-Prozess dokumentieren.
3. Muss-, Soll- und Kann-Anforderungen nach Inhalt, Technik, Betrieb und Governance klassifizieren.
4. Nicht geeignete Anwendungsfälle, etwa transaktionelle Portale oder stark personalisierte Inhalte, ausdrücklich abgrenzen.
5. Die Eignung anhand nachvollziehbarer Entscheidungskriterien bewerten und offene Annahmen kennzeichnen.

Praxisaufgabe

Für ein Beispielszenario wird eine Anforderungsmatrix erstellt und eine begründete Einsatzentscheidung vorbereitet.

2. Dokumentationspipeline und Artefakte

Die Verarbeitung von AsciiDoc-Quellen über Inhaltsaggregation, Klassifizierung, Konvertierung, UI und Veröffentlichung wird als durchgängiger Datenfluss betrachtet.

Schritt-für-Schritt: Den End-to-End-Datenfluss modellieren

1. Git-Repositories und Playbook-Projekt als Eingangsquellen im Kontextdiagramm anlegen.
2. Aggregation, Komponentenklassifizierung, AsciiDoc-Verarbeitung und UI-Zusammenführung als Verarbeitungsschritte ergänzen.
3. Erzeugte HTML-Seiten, Assets, Suchindex und optionale Exportformate als Artefakte kennzeichnen.
4. Vertrauensgrenzen, Zugangsdaten, temporäre Arbeitsverzeichnisse und Veröffentlichungsziele markieren.
5. Für jeden Übergang Verantwortliche, Fehlerbilder und notwendige Kontrollen festlegen.

Praxisaufgabe

Der Pipeline-Datenfluss wird für eine Organisation mit mehreren Produkt-Repositories gezeichnet und auf fehlende Kontrollen geprüft.

3. Zielarchitektur und Betriebsmodell

Aus den Anforderungen wird eine Architektur mit Repository-Modell, Build-Laufzeit, Bereitstellung, Rollen und Wartungsgrenzen abgeleitet.

Schritt-für-Schritt: Eine tragfähige Zielarchitektur entwerfen

1. Repository-Aufteilung nach Produkten, Teams, Releases und gemeinsamen Inhalten auswählen.
2. Build-Ausführung lokal, in einer CI/CD-Plattform oder in einem isolierten Container bewerten.
3. Ablage und Auslieferung der statischen Site einschließlich Cache-, CDN- und Zugriffskonzept festlegen.
4. Rollen für Inhaltseigentum, Plattformbetrieb, UI-Entwicklung, Freigabe und Incident-Bearbeitung zuordnen.
5. Nichtfunktionale Anforderungen wie Verfügbarkeit, Reproduzierbarkeit, Wiederanlauf und Aufbewahrung konkretisieren.
6. Architekturentscheidungen mit Alternativen, Konsequenzen und Prüfterminen dokumentieren.

Praxisaufgabe

Ein Referenzentwurf wird anhand von Skalierung, Sicherheitsbedarf und Teamstruktur bewertet und angepasst.

4. Pilotierung und Einführungsfahrplan

Die Einführung wird in überprüfbare Schritte zerlegt, damit technische Machbarkeit, redaktionelle Akzeptanz und Betriebsfähigkeit getrennt nachgewiesen werden können.

Schritt-für-Schritt: Vom Pilot zum geregelten Betrieb planen

1. Einen repräsentativen, aber begrenzten Pilotumfang mit klaren Ausschlüssen definieren.
2. Messbare Abnahmekriterien für Build, Navigation, Verlinkung, UI, Suche und Veröffentlichung festlegen.
3. Migration, Schulung, Betriebsübergabe und organisatorische Freigaben in Arbeitspakete zerlegen.
4. Risiken nach Eintrittswahrscheinlichkeit und Auswirkung priorisieren und Gegenmaßnahmen zuordnen.
5. Entscheidungspunkte für Fortführung, Nacharbeit oder Abbruch des Piloten terminieren.
6. Eine Reihenfolge für weiterführende Fachseminare anhand der geplanten Rollen ableiten.

Praxisaufgabe

Als Arbeitsergebnis entsteht ein priorisierter Einführungsfahrplan mit Pilotumfang, Abnahmekriterien und Verantwortlichkeiten.

Zielgruppe und Voraussetzungen

Zielgruppe: IT- und Lösungsarchitektur, technische Dokumentationsleitung, Plattformverantwortung, DevOps-Leitung, Produktverantwortung und technische Projektleitung.

Voraussetzungen: Grundverständnis von Git, statischer Webbereitstellung und technischen Dokumentationsprozessen; praktische Antora-Erfahrung ist nicht 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.