Seminar MkDocs – Lebenszyklus, Upgrade und Migrationsplanung

Dokumentationsplattformen bestehen aus MkDocs, Theme, Plugins, Markdown-Erweiterungen, Python-Laufzeit, eigenen Anpassungen und Build-Infrastruktur. Änderungen an einer Schicht können die gesamte Plattform betreffen. Deshalb benötigt jede produktive Installation ein technisches Inventar und einen kontrollierten Entscheidungsprozess.

Inhaltsübersicht

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

Zielsetzung

Für eine bestehende Plattform wird ein vollständiges Inventar erstellt. Upgrade, stabiler Weiterbetrieb und Migration werden anhand von Risiken, Pilotkriterien, Tests, Parallelbetrieb und Rollback nachvollziehbar bewertet.

Zielgruppe

Technische Architekten, Administratoren, DevOps-Teams, IT-Leitungen, Projektleitungen und Betreiber langfristig genutzter Dokumentationsplattformen.

Voraussetzungen

Praktische Erfahrung mit MkDocs, Abhängigkeiten, Git und Build-Prozessen; keine vertiefte Plugin-Entwicklung erforderlich.

Seminarinhalte

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

Technisches Inventar und Risikobewertung

1. Schritt 1: MkDocs-, Theme-, Plugin-, Python- und Build-Werkzeugversionen erfassen.
2. Schritt 2: Eigene Overrides, Skripte, Erweiterungen und externe Assets dokumentieren.
3. Schritt 3: Kritische, optionale und ersetzbare Abhängigkeiten kennzeichnen.
4. Schritt 4: Sicherheits-, Betriebs- und Funktionsrisiken getrennt priorisieren.

Upgrade in Staging und Kompatibilität

1. Schritt 1: Abhängigkeiten in isolierter Umgebung schrittweise aktualisieren.
2. Schritt 2: Konfiguration, Warnungen, Funktion und Darstellung gegen Referenzstand vergleichen.
3. Schritt 3: Kompatibilitätsgrenzen zwischen MkDocs-Generationen, Material und Plugins bewerten.
4. Schritt 4: Notwendige Anpassungen in einer nachvollziehbaren Migrationsliste erfassen.

Migrationsentscheidung, Pilot und Umschaltung

1. Schritt 1: Weiterbetrieb, Upgrade und Plattformwechsel anhand gewichteter Kriterien vergleichen.
2. Schritt 2: Repräsentativen Pilotbereich mit begrenztem Risiko auswählen.
3. Schritt 3: Inhalte, Konfiguration, Theme, Plugins und Pipeline als getrennte Stränge behandeln.
4. Schritt 4: Parallelbetrieb, Umschaltung, Rollback und nächsten Entscheidungstermin dokumentieren.

Lieferkette, Abhängigkeiten und Plugins

1. Schritt 1: Direkte und transitive Python-Abhängigkeiten vollständig inventarisieren.
2. Schritt 2: Versionen, Herkunft und unterstützte Bereiche festschreiben.
3. Schritt 3: Plugins als ausführbaren Code mit Berechtigungen und Seiteneffekten bewerten.
4. Schritt 4: Aktualisierungs- und Sicherheitsprüfung in den Lebenszyklus integrieren.

Qualitätsmodell und Prüfstrategie

1. Schritt 1: Inhaltliche, strukturelle, technische, visuelle und betriebliche Fehler unterscheiden.
2. Schritt 2: Fehler nach Auswirkung, Erkennbarkeit und Korrekturaufwand priorisieren.
3. Schritt 3: Lokale Prüfung, Review-Gate und vollständige Pipeline-Prüfung trennen.
4. Schritt 4: Akzeptanzkriterien und zeitlich begrenzte Ausnahmen dokumentieren.

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

• Abhängigkeiten, Anpassungen und Betriebsrisiken vollständig inventarisieren
• Ein Upgrade in isolierter Staging-Umgebung mit Referenzprüfungen planen
• Entscheidungsmatrix, Pilot, Parallelbetrieb und Rollback für eine Migration ausarbeiten

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.