Seminar Antora – Migration bestehender Dokumentationslandschaften

Beschreibung

Das Seminar behandelt die kontrollierte Migration bestehender Dokumentationsbestände nach Antora. Quellformate, Informationsarchitektur, URLs, interne Verweise, Bilder, Anhänge, wiederverwendete Inhalte und Freigabeprozesse werden inventarisiert und in ein Zielmodell überführt. Eine Migrationswelle wird einschließlich Konvertierung, Parallelbetrieb, Abnahme, Umschaltung und Rückfallplan praktisch vorbereitet.

Inhaltsübersicht

1. Migrationsinventar und Risikoklassifikation
2. Zielmodell für Komponenten und Module
3. Konvertierung nach AsciiDoc
4. Ressourcen-IDs, Links und URL-Kontinuität
5. Assets, Partials und gemeinsame Inhalte
6. Parallelbuild, Qualität und Abnahme
7. Cutover, Rollback und Migrationswellen

Lernziele

• Bestände, Abhängigkeiten und Qualitätsrisiken einer Migration vollständig erfassen.
• Bestehende Strukturen in ein tragfähiges Antora-Content-Modell überführen.
• Konvertierung, Links, URLs und Assets mit automatisierten Kontrollen absichern.
• Parallelbetrieb, Abnahme, Umschaltung und Rückfall nachvollziehbar planen.

1. Migrationsinventar und Risikoklassifikation

Eine belastbare Migration beginnt mit einem quantifizierten Inventar statt mit einzelnen Konvertierungsversuchen.

Schritt-für-Schritt: Den Ausgangsbestand systematisch erfassen

1. Quellsysteme, Formate, Versionen, Sprachen und Veröffentlichungsziele inventarisieren.
2. Seiten, Bilder, Downloads, Codebeispiele, Vorlagen und wiederverwendete Fragmente zählen.
3. Interne und externe Verweise, Weiterleitungen und bekannte Einstiegspunkte erfassen.
4. Inhalte nach Aktualität, Kritikalität, Komplexität und Eigentümerschaft klassifizieren.
5. Technische und redaktionelle Sonderfälle als Risikoregister dokumentieren.
6. Eine repräsentative Stichprobe für den Migrationsprototyp auswählen.

Praxisaufgabe

Für einen Beispielbestand entsteht ein Migrationsinventar mit Mengen, Eigentümern und Risikoklassen.

2. Zielmodell für Komponenten und Module

Bestehende Ordner oder Navigationsbäume werden nicht unbesehen übernommen, sondern in eine wartbare Antora-Struktur überführt.

Schritt-für-Schritt: Die Zielarchitektur für Inhalte entwerfen

1. Fachliche Produkt- und Releasegrenzen aus dem Inventar ableiten.
2. Komponenten, Versionen und Module anhand von Verantwortlichkeit und Nutzungszusammenhang definieren.
3. Ressourcenfamilien für Seiten, Bilder, Beispiele, Anhänge und Partials zuordnen.
4. Regeln für gemeinsame Inhalte und Querschnittsthemen festlegen.
5. Zielnavigation nach Nutzeraufgaben statt nach Altsystemstruktur entwerfen.
6. Alt-zu-Neu-Zuordnung in einer Mapping-Tabelle dokumentieren und fachlich abnehmen.

Praxisaufgabe

Ein historisch gewachsener Navigationsbaum wird in ein neues Komponenten- und Modulmodell übersetzt.

3. Konvertierung nach AsciiDoc

Quellinhalte werden mit kontrollierter Automatisierung und redaktioneller Nachbearbeitung nach AsciiDoc überführt.

Schritt-für-Schritt: Eine reproduzierbare Konvertierungspipeline erstellen

1. Eingabeformate und benötigte Konvertierungsregeln je Inhaltstyp festlegen.
2. Vorverarbeitung für Zeichensatz, Zeilenenden, Metadaten und eingebettete Assets definieren.
3. Überschriften, Listen, Tabellen, Links, Codeblöcke und Hinweise in AsciiDoc-Strukturen überführen.
4. Nicht automatisch konvertierbare Konstrukte mit eindeutigen Markierungen versehen.
5. Konvertierte Dateien formatieren, validieren und in die Zielverzeichnisse schreiben.
6. Konvertierung mit Stichproben und wiederholtem Lauf auf Determinismus prüfen.

Praxisaufgabe

Eine heterogene Beispielmenge wird automatisiert konvertiert und anhand einer Fehlerliste redaktionell bereinigt.

4. Ressourcen-IDs, Links und URL-Kontinuität

Verweise und etablierte URLs sind häufig das größte technische Migrationsrisiko.

Schritt-für-Schritt: Alte Referenzen zuverlässig auf neue Ziele abbilden

1. Interne Links aus den Quellen extrahieren und nach Zieltyp klassifizieren.
2. Für jede Zielseite eine stabile Ressourcen-ID und einen geplanten Ausgabepfad bestimmen.
3. Interne Links in lokale, modul-, komponenten- oder versionsübergreifende Xrefs umwandeln.
4. Alte öffentliche URLs einer neuen Zielseite oder einer bewusst entfernten Ressource zuordnen.
5. Weiterleitungsregeln mit Schleifen-, Ketten- und Zielprüfung validieren.
6. Link- und Redirect-Berichte als verpflichtendes Migrationsartefakt erzeugen.

Praxisaufgabe

Ein Linknetz mit veralteten relativen Pfaden wird in Xrefs und eine geprüfte Redirect-Matrix überführt.

5. Assets, Partials und gemeinsame Inhalte

Bilder, Anhänge, Beispiele und wiederverwendete Textbausteine benötigen eigene Migrationsregeln.

Schritt-für-Schritt: Nichtseitige Ressourcen kontrolliert übernehmen

1. Assets nach Typ, Verwendung, Dateigröße, Lizenzstatus und Dublette analysieren.
2. Dateinamen und Verzeichniszuordnung nach den Zielkonventionen normalisieren.
3. Bildverweise, Downloads und Codebeispiele auf Antora-Ressourcen-IDs umstellen.
4. Wiederkehrende Textteile auf Eignung als Partial oder Attribut prüfen.
5. Veraltete oder ungenutzte Ressourcen nur nach dokumentierter Freigabe aussondern.
6. Build und visuelle Stichproben auf fehlende, falsche oder verzerrte Assets prüfen.

Praxisaufgabe

Ein Bestand aus Bildern, Anhängen und Textfragmenten wird bereinigt und in passende Ressourcenfamilien migriert.

6. Parallelbuild, Qualität und Abnahme

Alt- und Neusystem werden zeitweise parallel verglichen, um Inhalts- und Darstellungsverluste sichtbar zu machen.

Schritt-für-Schritt: Eine nachvollziehbare Migrationsabnahme durchführen

1. Abnahmekriterien für Inhalt, Navigation, Links, Assets, Suche und Darstellung definieren.
2. Altsystem und Antora-Ausgabe für denselben Migrationsumfang bereitstellen.
3. Automatisierte Struktur-, Link- und Dateiprüfungen ausführen.
4. Fachliche Stichproben mit Content Ownern und repräsentativen Nutzeraufgaben durchführen.
5. Abweichungen nach Kritikalität priorisieren und Nacharbeit eindeutig zuordnen.
6. Freigabe mit Prüfnachweisen, bekannten Restpunkten und Entscheidung dokumentieren.

Praxisaufgabe

Eine Migrationswelle wird mit automatischem Prüfbericht und fachlichem Abnahmeprotokoll bewertet.

7. Cutover, Rollback und Migrationswellen

Die Umschaltung wird als kontrollierter Betriebswechsel mit Rückfallmöglichkeit geplant.

Schritt-für-Schritt: Die Migration sicher in Produktion überführen

1. Migrationswellen nach Produkt, Version, Risiko und Abhängigkeit zuschneiden.
2. Änderungsstopp, letzte Synchronisierung und finalen Build terminieren.
3. Weiterleitungen, DNS-, Webserver- oder Deploymentänderungen in eine genaue Ablaufsequenz überführen.
4. Smoke Tests und fachliche Freigaben unmittelbar nach der Umschaltung definieren.
5. Rollback-Auslöser, Rückschaltreihenfolge und Datenstand eindeutig festlegen.
6. Kommunikation, Supportbereitschaft und Nachbeobachtung für jede Welle planen.

Praxisaufgabe

Als Arbeitsergebnis entsteht ein Cutover- und Rollback-Runbook für eine vollständige Migrationswelle.

Zielgruppe und Voraussetzungen

Zielgruppe: Technische Redaktionsleitung, Content- und Informationsarchitektur, Documentation Engineers, Web- und Plattformteams, DevOps, Qualitätsmanagement und technische Projektleitung.

Voraussetzungen: Grundverständnis von Git und Antora sowie Kenntnisse der zu migrierenden Dokumentationsplattform oder Quellformate.

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.