Seminar MkDocs – Versionierte Dokumentation und Release-Portale

Produktdokumentation muss häufig mehrere Versionen parallel bereitstellen, ohne Nutzer in veraltete Inhalte zu führen. Dafür werden ein nachvollziehbares Versionsmodell, stabile URLs, getrennte Builds, Versionsauswahl, Suchstrategie und klare Archivierungsregeln benötigt.

Inhaltsübersicht

• Zielsetzung
• Zielgruppe
• Voraussetzungen
• Seminarinhalte
• Praxisübungen
• Methodik

Zielsetzung

Ein mehrversioniger Prototyp wird aufgebaut. Unterstützte, zukünftige und archivierte Stände werden getrennt, mit eindeutigen Einstiegen versehen und in einen reproduzierbaren Release- und Hotfix-Prozess integriert.

Zielgruppe

Release-Manager, technische Redaktionen, Produktteams, DevOps-Verantwortliche und Betreiber versionierter Dokumentationsportale.

Voraussetzungen

Grundkenntnisse in Git, MkDocs und Build-Prozessen; Erfahrung mit Produktversionen und Releases ist hilfreich.

Seminarinhalte

Die Themen werden in einer festen Arbeitsfolge aus Analyse, Einrichtung, Umsetzung und Prüfung bearbeitet.

Versionsmodell und URL-Strategie

1. Schritt 1: Unterstützte Produktstände und tatsächliche Nutzerbedürfnisse erfassen.
2. Schritt 2: Aktuelle, zukünftige und archivierte Versionen eindeutig unterscheiden.
3. Schritt 3: Versionspräfixe, kanonische Einstiege und Warnhinweise planen.
4. Schritt 4: Abkündigungs-, Archivierungs- und Aufbewahrungsregeln festlegen.

Mehrversionige Builds und Versionsauswahl

1. Schritt 1: Branches, Tags oder getrennte Quellen nach Pflegebedarf auswählen.
2. Schritt 2: Mehrere Stände in reproduzierbaren Builds und konsistenten Zielpfaden erzeugen.
3. Schritt 3: Versionsauswahl und Metadaten in Theme oder Portal integrieren.
4. Schritt 4: Suche, Weiterleitungen, Hotfixes und Rollback je Version absichern.

Releases und Nachvollziehbarkeit

1. Schritt 1: Dokumentationsstände mit Produktversionen oder Veröffentlichungsterminen verbinden.
2. Schritt 2: Tags, Änderungsprotokolle und Freigabevermerke konsistent einsetzen.
3. Schritt 3: Hotfixes und Rückportierungen für veröffentlichte Stände organisieren.
4. Schritt 4: Einen Auditpfad von Anforderung, Änderung und Review bis zur Veröffentlichung herstellen.

Navigation und Benutzerführung

1. Schritt 1: Nutzeraufgaben, Einstiegspunkte und erwartete Informationswege erfassen.
2. Schritt 2: Explizite Navigation mit sinnvoller Tiefe, Gruppierung und Reihenfolge aufbauen.
3. Schritt 3: Seitennavigation, Inhaltsverzeichnis, Tabs und Abschnittsübersichten abstimmen.
4. Schritt 4: Navigation anhand realer Such- und Arbeitsaufgaben überprüfen.

Suche und Auffindbarkeit

1. Schritt 1: Fachbegriffe, Synonyme, Fehlvarianten und zentrale Suchaufgaben erfassen.
2. Schritt 2: Suchsprache, Indexierung, Gewichtung und Ausschlüsse passend konfigurieren.
3. Schritt 3: Seitentitel, Überschriften und Metadaten auf Suchrelevanz prüfen.
4. Schritt 4: Suchqualität mit einem wiederholbaren Testkatalog messen.

Governance und Pflegeprozess

1. Schritt 1: Eigentümerschaft, Review-Intervall und Freigabestufe pro Bereich festlegen.
2. Schritt 2: Verfallsdaten, Archivierung und Kennzeichnung veralteter Inhalte definieren.
3. Schritt 3: Änderungsprozesse zwischen Redaktion, Entwicklung und Betrieb koordinieren.
4. Schritt 4: Kennzahlen und regelmäßige Bestandsbereinigung etablieren.

Praxisübungen

• Ein Versions- und URL-Modell für mehrere Produktstände festlegen
• Mehrere Dokumentationsstände reproduzierbar bauen und auswählbar machen
• Release, Hotfix, Archivierung und Abkündigung als Prozess definieren

Methodik

Fachliche Einführung, nachvollziehbare Demonstration, angeleitete Umsetzung, selbstständige Übungsphasen, strukturierte Fehleranalyse und gemeinsame Qualitätskontrolle wechseln einander ab. Alle Arbeitsschritte werden an einem zusammenhängenden Beispielprojekt durchgeführt.