Seminar MkDocs – Intensivseminar Komplett mit Material for MkDocs

Dieses Intensivseminar bietet einen verdichteten Gesamtüberblick über das vollständige Seminarportfolio. Redaktion, Informationsarchitektur, Material-Gestaltung, Git-Arbeit, Qualitätssicherung, CI/CD, Betrieb, Sicherheit, Erweiterung, Versionierung und Lebenszyklus werden in einem einzigen End-to-End-Projekt zusammengeführt.

Inhaltsübersicht

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

Zielsetzung

Eine produktionsnahe Dokumentationsplattform wird von der Anforderungsanalyse bis zur kontrollierten Veröffentlichung aufgebaut. Die Teilnehmenden erhalten ein Gesamtmodell, das Verantwortlichkeiten, Quellen, Konfiguration, Gestaltung, Prüfungen und Betrieb miteinander verbindet.

Zielgruppe

Technische Projektleitungen, Plattformverantwortliche, erfahrene Redakteure, Entwickler und Administratoren, die das Gesamtsystem beurteilen oder ein Einführungsvorhaben steuern müssen.

Voraussetzungen

Grundkenntnisse in Markdown, Git, YAML und Kommandozeile; für die Entwicklungsanteile sind Python-, HTML- und CSS-Grundkenntnisse hilfreich.

Seminarinhalte

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

Projektstruktur und erster Build

1. Schritt 1: Projektgerüst mit Konfiguration, Inhaltsverzeichnis und Ausgabeordner anlegen.
2. Schritt 2: Quellen, Konfiguration, Assets und generierte Ausgabe sauber trennen.
3. Schritt 3: Lokalen Entwicklungsserver starten und Änderungen unmittelbar prüfen.
4. Schritt 4: Produktionsbuild ausführen und Warnungen geordnet auswerten.

Technisches Markdown und Seitentypen

1. Schritt 1: Überschriften, Listen, Links, Bilder, Tabellen und Code semantisch korrekt einsetzen.
2. Schritt 2: Anleitungen mit Voraussetzungen, nummerierten Schritten und Prüfergebnis strukturieren.
3. Schritt 3: Konzepte, Referenzen, Tutorials und Fehlerbehebungen klar unterscheiden.
4. Schritt 4: Interne Verweise und Medienpfade relativ, stabil und wartbar aufbauen.

Informationsarchitektur und Taxonomie

1. Schritt 1: Zielgruppen, Aufgaben und fachliche Inhaltsarten voneinander trennen.
2. Schritt 2: Bestand inventarisieren sowie Dubletten, Lücken und veraltete Inhalte markieren.
3. Schritt 3: Taxonomie, Terminologie und kontrollierte Metadaten entwickeln.
4. Schritt 4: Zielstruktur mit Karten-Sortierung und Nutzungsszenarien validieren.

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.

Material for MkDocs einrichten

1. Schritt 1: Theme aktivieren und Sprache, Farbschema, Logo sowie Grundfunktionen konfigurieren.
2. Schritt 2: Suche, Navigationsmerkmale und geeignete Markdown-Erweiterungen einschalten.
3. Schritt 3: Darstellung auf Desktop, Tablet, Mobilgerät und in Druckansichten prüfen.
4. Schritt 4: Konfigurationsentscheidungen in einer wartbaren Theme-Baseline festhalten.

Erweiterte Inhaltskomponenten

1. Schritt 1: Hinweise, Details, Tabs, Grids und Annotationen nach fachlichem Zweck auswählen.
2. Schritt 2: Codeblöcke mit Sprache, Markierung, Zeilennummern und erklärenden Anmerkungen gestalten.
3. Schritt 3: Tabellen, Aufgabenlisten, Definitionen und Fußnoten konsistent einsetzen.
4. Schritt 4: Komponentenregeln gegen Überladung und uneinheitliche Verwendung formulieren.

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.

Branches, Review und Konfliktlösung

1. Schritt 1: Branches nach Zweck und begrenzter Lebensdauer verwenden.
2. Schritt 2: Reviews für Inhalt, Technik, Terminologie und Darstellung getrennt durchführen.
3. Schritt 3: Konflikte in Navigation und Text fachlich vor der technischen Auflösung klären.
4. Schritt 4: Nach dem Zusammenführen Build, Links und Seitendarstellung erneut prüfen.

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.

CI/CD-Stufenmodell

1. Schritt 1: Ereignisse für Prüfung, Vorschau, Freigabe und Veröffentlichung festlegen.
2. Schritt 2: Pipeline-Stufen nach Geschwindigkeit, Risiko und Abhängigkeit ordnen.
3. Schritt 3: Artefakte, Protokolle und Freigaben als überprüfbare Ergebnisse definieren.
4. Schritt 4: Abbruch-, Wiederanlauf- und Fehlerregeln vor der Implementierung festlegen.

Build-Artefakte und Vorschauumgebungen

1. Schritt 1: Statische Ausgabe als unveränderliches, versioniertes Artefakt behandeln.
2. Schritt 2: Quellrevision, Build-Zeitpunkt und Abhängigkeitsstand nachweisbar einbetten.
3. Schritt 3: Isolierte Vorschauen für Reviews mit eindeutiger Lebensdauer bereitstellen.
4. Schritt 4: Artefakte zwischen Pipeline-Stufen weitergeben statt erneut zu bauen.

Deployment und Veröffentlichung

1. Schritt 1: Zielsystem und Übertragungsstrategie nach Betriebsanforderung auswählen.
2. Schritt 2: Veröffentlichung atomar oder über versionierte Zielverzeichnisse durchführen.
3. Schritt 3: Berechtigungen, Cache-Invalidierung und konsistente Assets berücksichtigen.
4. Schritt 4: Produktiven Stand nach Veröffentlichung technisch und fachlich prüfen.

Betriebsbaseline und Runbooks

1. Schritt 1: Normale Build-Zeit, Artefaktgröße und Veröffentlichungsdauer als Baseline erfassen.
2. Schritt 2: Betriebs-, Wartungs- und Störungsaufgaben in Runbooks strukturieren.
3. Schritt 3: Sicherung von Quellen, Konfiguration, Abhängigkeiten und Artefakten festlegen.
4. Schritt 4: Pflegeintervalle, Verantwortlichkeiten und Wartungsfenster terminieren.

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.

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.

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.

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

• Eine Zielarchitektur mit Rollen, Repository und Navigationsmodell entwerfen
• Ein Material-Portal mit Komponenten, Metadaten und Qualitäts-Gates umsetzen
• Pipeline, Veröffentlichung, Rollback und Lebenszyklusentscheidung als Gesamtabnahme durchführen

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.