Seminar MkDocs – Docs-as-Code mit Git

Docs-as-Code überträgt bewährte Entwicklungspraktiken auf technische Dokumentation. Damit dies nicht nur ein Schlagwort bleibt, müssen Repository-Struktur, Branching, Reviews, Freigaben, Änderungsnachweise und redaktionelle Rollen sinnvoll zusammenpassen.

Inhaltsübersicht

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

Zielsetzung

Ein vollständiger Git-basierter Arbeitsablauf wird aufgebaut: von der Aufgabenbeschreibung über Branch und Review bis zur freigegebenen, nachvollziehbaren Änderung an einem MkDocs-Projekt.

Zielgruppe

Technische Redaktionen, Entwickler, Produktteams, Qualitätssicherung und Teamleitungen, die Dokumentation gemeinsam im Repository pflegen.

Voraussetzungen

Grundkenntnisse in Markdown; erste Git-Erfahrung ist hilfreich, aber nicht zwingend erforderlich.

Seminarinhalte

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

Repository-Struktur und Git-Grundablauf

1. Schritt 1: Dokumentationsquellen, Konfiguration, Assets und Hilfsskripte sinnvoll ordnen.
2. Schritt 2: Kleine, thematisch geschlossene Änderungen erstellen und prüfen.
3. Schritt 3: Aussagekräftige Commits mit fachlichem Bezug formulieren.
4. Schritt 4: Generierte Ausgabe und sensible lokale Dateien aus dem Repository fernhalten.

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.

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.

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.

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

• Ein Dokumentations-Repository mit klaren Verantwortungsbereichen strukturieren
• Eine Änderung über Branch, Commit, Review und Freigabe durchführen
• Review-Checklisten und Regeln für Hotfixes sowie parallele Änderungen formulieren

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.