Seminar Docusaurus – Versionierung und Release-Dokumentation

Inhaltsübersicht

1. Zielsetzung
2. Schritt 1: Versionsbedarf und Lebenszyklus bewerten
3. Schritt 2: Current- und Snapshot-Modell festlegen
4. Schritt 3: Version erzeugen und Dateien verstehen
5. Schritt 4: Navigation und Versionsauswahl konfigurieren
6. Schritt 5: Korrekturen und gemeinsame Inhalte behandeln
7. Schritt 6: Release Notes und Produktkommunikation integrieren
8. Schritt 7: Sprachen und mehrere Docs-Bereiche koordinieren
9. Schritt 8: Automatisierung und Außerbetriebnahme etablieren
10. Praxisphasen
11. Zielgruppe und Voraussetzungen

Zielsetzung

Das Seminar entwickelt ein belastbares Versions- und Veröffentlichungskonzept für Docusaurus-Dokumentation. Current- und Snapshot-Modell, Versionsseiten, Sidebars, Auswahlkomponenten, Ablösung, Release Notes, Blog, Automatisierung, Sprachen und Pflegeaufwand werden gemeinsam geplant.

• Versionierung nur dort einsetzen, wo Produkt- und Nutzeranforderungen sie rechtfertigen
• Snapshots, Routen, Sidebars und Versionsauswahl konsistent konfigurieren
• Release-Dokumentation und Änderungsinformationen mit Produktständen verbinden
• ältere Versionen kontrolliert pflegen, kennzeichnen und außer Betrieb nehmen

Seminarinhalte

Schritt 1: Versionsbedarf und Lebenszyklus bewerten

Nicht jede Dokumentation benötigt parallele Versionen. Supportdauer, Produktkompatibilität, Änderungsdichte und Nutzererwartung bestimmen, ob Snapshots, nur aktuelle Inhalte oder getrennte Sites sinnvoll sind.

• Produkt- und Supportversionen erfassen
• Kosten paralleler Pflege bewerten
• Entscheidungsregeln für neue Snapshots festlegen

Schritt 2: Current- und Snapshot-Modell festlegen

Der aktuelle Arbeitsstand und eingefrorene Versionen erhalten klare Bezeichnungen, Pfade und Zuständigkeiten. Die Bedeutung von latest, current und next wird für Nutzende und Redaktion eindeutig definiert.

• Versionsbezeichnungen und Banner formulieren
• Routen für aktuelle und ältere Stände planen
• Standardversion und letzte unterstützte Version bestimmen

Schritt 3: Version erzeugen und Dateien verstehen

Ein Snapshot kopiert Dokumente und Sidebar-Konfiguration in versionierte Bereiche. Vor dem Erzeugen werden IDs, Links, generierte Inhalte und offene Änderungen geprüft, damit kein inkonsistenter Stand eingefroren wird.

• Snapshot-Checkliste ausführen
• Versionsbefehl kontrolliert anwenden
• versionierte Dokumente, Sidebars und Versionsliste prüfen

Schritt 4: Navigation und Versionsauswahl konfigurieren

Versionsdropdown, Banner, Sidebar und Landingpages zeigen den aktiven Stand eindeutig. Verweise zwischen Versionen werden vermieden oder ausdrücklich gekennzeichnet.

• Versionsauswahl in Navbar integrieren
• Banner für aktuelle, nächste und veraltete Stände gestalten
• Navigation auf Mischzustände testen

Schritt 5: Korrekturen und gemeinsame Inhalte behandeln

Fehlerkorrekturen können mehrere unterstützte Versionen betreffen, während neue Funktionen nur in den aktuellen Stand gehören. Gemeinsame Inhalte werden anhand ihres Lebenszyklus entweder kopiert oder bewusst zentral geführt.

• Backport-Regeln für Dokumentationskorrekturen definieren
• gemeinsame und versionsgebundene Inhalte unterscheiden
• Änderungen in mehreren Ständen nachvollziehbar dokumentieren

Schritt 6: Release Notes und Produktkommunikation integrieren

Release Notes, Blogbeiträge und Dokumentationsänderungen erfüllen unterschiedliche Aufgaben. Eine gemeinsame Veröffentlichungsmatrix verbindet Änderungstyp, Zielgruppe, Detailtiefe und dauerhaften Dokumentationsort.

• Release-Note-Struktur und Kategorien festlegen
• Blog für zeitbezogene Kommunikation einsetzen
• dauerhafte Anleitungen und Konzepte zeitnah aktualisieren

Schritt 7: Sprachen und mehrere Docs-Bereiche koordinieren

Versionen können je Content-Plugin-Instanz und Locale unterschiedliche Pflegezyklen haben. Snapshot und Übersetzung werden so koordiniert, dass unterstützte Kombinationen klar erkennbar bleiben.

• Versionsmatrix je Dokumentationsbereich erstellen
• Übersetzungspriorität nach Supportstand festlegen
• fehlende Kombinationen kontrolliert kennzeichnen

Schritt 8: Automatisierung und Außerbetriebnahme etablieren

Snapshot-Erzeugung, Build, Linktests und Freigabe werden automatisiert, ohne die fachliche Entscheidung zu ersetzen. Nicht mehr unterstützte Versionen erhalten Ankündigung, Archivierung oder Entfernung mit stabilen Weiterleitungen.

• Release-Pipeline und Snapshot-Check automatisieren
• Ablösefristen und Verantwortliche festlegen
• Archiv-, Redirect- und Löschstrategie umsetzen

Praxisphasen

Die einzelnen Arbeitsschritte werden an einer durchgängigen Übungsplattform umgesetzt. Konfigurationen, Inhalte und Prüfungen werden schrittweise erweitert und jeweils mit einem produktionsnahen Build kontrolliert.

• Entwurf einer Versionsstrategie für ein Produkt mit mehreren Supportständen
• Erzeugung und Konfiguration eines Dokumentations-Snapshots mit Dropdown, Banner und Sidebar
• Aufbau einer Veröffentlichungsmatrix für Dokumentation, Release Notes und Blog

Zielgruppe und Voraussetzungen

Zielgruppe: Release-Verantwortliche, technische Redaktionen, Produktteams, Docusaurus-Administratoren und Developer-Portal-Teams

Voraussetzungen: Docusaurus-Grundkenntnisse, Erfahrung mit Sidebars und Git; Verständnis des eigenen Produkt- und Release-Lebenszyklus