Seminar Docusaurus – Content-Qualität, Tests und Governance

Inhaltsübersicht

1. Zielsetzung
2. Schritt 1: Qualitätsziele und Fehlertypen definieren
3. Schritt 2: Inhaltstypen und Metadaten standardisieren
4. Schritt 3: Markdown und MDX statisch prüfen
5. Schritt 4: Links, Assets und Routen validieren
6. Schritt 5: Build- und Komponententests ergänzen
7. Schritt 6: Review und Eigentümerschaft organisieren
8. Schritt 7: Aktualität und Ablösung steuern
9. Schritt 8: Qualitätskennzahlen und Verbesserungszyklus etablieren
10. Praxisphasen
11. Zielgruppe und Voraussetzungen

Zielsetzung

Das Seminar überführt Qualitätsanforderungen an technische Inhalte in prüfbare Regeln und klare Verantwortlichkeiten. Redaktionelle Standards, Front Matter, Linting, Link- und Asset-Prüfung, Build-Gates, Reviews, Aktualität und Ablöseprozesse werden zu einem gemeinsamen System verbunden.

• ein messbares Qualitätsmodell für Docusaurus-Inhalte definieren
• Inhaltsregeln und technische Prüfungen sinnvoll automatisieren
• Eigentümerschaft, Review und Freigabe transparent organisieren
• veraltete, fehlerhafte und doppelte Inhalte kontrolliert erkennen und behandeln

Seminarinhalte

Schritt 1: Qualitätsziele und Fehlertypen definieren

Qualität wird in fachliche Richtigkeit, Verständlichkeit, Konsistenz, Auffindbarkeit, technische Integrität und Aktualität zerlegt. Für jede Kategorie werden prüfbare Kriterien und angemessene Reaktionen festgelegt.

• kritische und nichtkritische Fehler unterscheiden
• Mindestkriterien je Inhaltstyp bestimmen
• Qualitätsbudgets und Ausnahmen dokumentieren

Schritt 2: Inhaltstypen und Metadaten standardisieren

Tutorials, Aufgabenanleitungen, Konzepte und Detailbeschreibungen erhalten jeweils passende Vorlagen. Front-Matter-Felder werden mit Datentyp, Pflichtstatus und erlaubten Werten definiert.

• Inhaltstypen und Vorlagenkatalog erstellen
• IDs, Slugs, Beschreibungen und Zuständigkeiten vereinheitlichen
• Metadatenänderungen versionierbar halten

Schritt 3: Markdown und MDX statisch prüfen

Syntaxregeln, Überschriftenstruktur, verbotene Muster und redaktionelle Konventionen werden automatisiert geprüft. Die Regeln bleiben nachvollziehbar und können bei begründeten Sonderfällen gezielt ausgesetzt werden.

• Syntax- und Stilregeln konfigurieren
• Fehlermeldungen mit konkreten Korrekturhinweisen formulieren
• Ausnahmen lokal und begründet dokumentieren

Schritt 4: Links, Assets und Routen validieren

Interne Verweise, Bilder, Downloads und erzeugte Routen werden auf Existenz und Eindeutigkeit geprüft. Umbenennungen erhalten eine kontrollierte Behandlung, damit bestehende Einstiege nicht unbemerkt brechen.

• relative Links und Anker prüfen
• nicht verwendete oder fehlende Assets erkennen
• doppelte Slugs und Route-Konflikte blockieren

Schritt 5: Build- und Komponententests ergänzen

Der produktive Build bildet das zentrale Integrationsgate. Kritische MDX- und React-Komponenten erhalten zusätzliche Tests für Rendering, Props, Zugänglichkeit und serverseitige Ausführung.

• Produktions-Build in jeder relevanten Änderung ausführen
• repräsentative Seiten und Komponenten testen
• SSR- und Hydrationsfehler gezielt abdecken

Schritt 6: Review und Eigentümerschaft organisieren

Änderungen werden nach Fachlichkeit, Redaktion, Technik und Freigabe unterschieden. Code-Owner, Inhaltsverantwortliche und Eskalationswege verhindern unklare Zuständigkeiten.

• Review-Matrix nach Änderungstyp erstellen
• Eigentümer je Inhaltsbereich hinterlegen
• Servicezeiten und Eskalation für kritische Fehler definieren

Schritt 7: Aktualität und Ablösung steuern

Inhalte erhalten Prüffristen, Status und eine nachvollziehbare Beziehung zu Produktversionen. Veraltete Seiten werden aktualisiert, gekennzeichnet, umgeleitet oder entfernt, ohne den Informationsfluss zu unterbrechen.

• Prüfdatum und Verantwortliche erfassen
• Ablöse- und Archivierungsregeln definieren
• veraltete Inhalte in Berichten sichtbar machen

Schritt 8: Qualitätskennzahlen und Verbesserungszyklus etablieren

Befunde, Build-Stabilität, Aktualitätsquote und Review-Dauer werden regelmäßig ausgewertet. Regeln werden anhand realer Fehlerbilder angepasst, ohne die Pipeline mit wirkungslosen Kontrollen zu überladen.

• wenige aussagekräftige Kennzahlen auswählen
• Fehlalarme und Regelwirksamkeit überprüfen
• Verbesserungen priorisiert in den Arbeitsprozess übernehmen

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.

• Erstellung eines Qualitätsmodells mit Kriterien, Schweregraden und Definition-of-Done
• Aufbau einer Prüfstrecke für Front Matter, Markdown, Links, Assets und Produktions-Build
• Entwurf eines Governance-Modells mit Eigentümerschaft, Review-Matrix und Aktualitätssteuerung

Zielgruppe und Voraussetzungen

Zielgruppe: Technische Redaktionen, Documentation Engineers, Qualitätsmanagement, Plattformteams und Verantwortliche für Redaktionsprozesse

Voraussetzungen: Docusaurus- und Markdown-Grundkenntnisse, Grundverständnis von Git-basierten Reviews; Programmierkenntnisse sind nicht zwingend erforderlich