Seminar MkDocs – Qualitätssicherung, Tests und Linkprüfung

Fehler in Dokumentation reichen von ungültigen Links und fehlenden Medien über falsche Metadaten bis zu beschädigter Navigation oder unbemerkten Darstellungsänderungen. Ein belastbares Qualitätsmodell kombiniert schnelle lokale Prüfungen mit zentralen Build- und Abnahmestufen.

Inhaltsübersicht

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

Zielsetzung

Ein mehrstufiges Testkonzept wird aufgebaut und an fehlerhaften Beispielseiten erprobt. Es umfasst Quellen, Links, erzeugtes HTML, Barriereaspekte, kritische Seitentypen, Ausnahmen und verständliche Fehlerberichte.

Zielgruppe

Technische Redaktionen, Qualitätssicherung, Entwickler, DevOps-Teams und Betreiber von Dokumentationsportalen.

Voraussetzungen

Grundkenntnisse in MkDocs, Git und Kommandozeile; Programmiererfahrung ist hilfreich, aber nicht zwingend.

Seminarinhalte

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

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.

Link-, Anker- und Medienprüfung

1. Schritt 1: Relative Links, Anker und Dateipfade gegen den Quellbestand prüfen.
2. Schritt 2: Verwaiste Dateien, fehlende Bilder und ungenutzte Medien erkennen.
3. Schritt 3: Weiterleitungen und bewusst nicht prüfbare Ziele dokumentieren.
4. Schritt 4: Fehler mit präziser Datei- und Zeilenangabe ausgeben.

HTML-, Barriere- und Regressionstests

1. Schritt 1: Erzeugte Seiten auf erwartete Titel, Metadaten und Navigation prüfen.
2. Schritt 2: Semantische HTML-Struktur, eindeutige IDs und Alternativtexte kontrollieren.
3. Schritt 3: Kritische Seitentypen und Bildschirmgrößen für visuelle Vergleiche auswählen.
4. Schritt 4: Beabsichtigte und fehlerhafte Darstellungsänderungen nachvollziehbar unterscheiden.

Qualitätsgates im Build

1. Schritt 1: Konfiguration, Markdown und Metadaten mit schnellen Prüfungen validieren.
2. Schritt 2: Strikten MkDocs-Build als verbindliches Gate einrichten.
3. Schritt 3: Links, Anker, Medienpfade und erzeugte HTML-Struktur kontrollieren.
4. Schritt 4: Fehlerausgaben mit Datei, Zeile, Regel und Verantwortungsbereich erzeugen.

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.

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

• Fehlerklassen und Akzeptanzkriterien für ein Beispielportal definieren
• Link-, Medien- und HTML-Prüfungen mit präzisen Fehlerausgaben aufbauen
• Lokale Checks, Review-Gates und vollständige Pipeline-Prüfung staffeln

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.