Seminar Docusaurus – Docs-as-Code und Redaktionsworkflows

Inhaltsübersicht

1. Zielsetzung
2. Schritt 1: Rollen und Arbeitsgegenstände abgrenzen
3. Schritt 2: Repository-Struktur für Redaktion gestalten
4. Schritt 3: Anforderung und Planung standardisieren
5. Schritt 4: Lokale Autorenerfahrung vereinfachen
6. Schritt 5: Inhaltsvorlagen und Konventionen einsetzen
7. Schritt 6: Branch- und Änderungsmodell festlegen
8. Schritt 7: Review und Qualitätsgates verbinden
9. Schritt 8: Freigabe, Release und Pflege organisieren
10. Praxisphasen
11. Zielgruppe und Voraussetzungen

Zielsetzung

Das Seminar gestaltet einen durchgängigen Docs-as-Code-Prozess für Docusaurus von der Anforderung bis zur veröffentlichten Änderung. Rollen, Repository-Struktur, lokale Vorschau, Vorlagen, Reviews, Freigaben, Release-Kopplung und Pflegeverantwortung werden zu einem praxistauglichen Redaktionsworkflow verbunden.

• redaktionelle und technische Arbeit in einem gemeinsamen Git-basierten Prozess organisieren
• Vorlagen, Branches, Reviews und Freigaben an Inhaltstyp und Risiko ausrichten
• lokale Vorschau und automatisierte Prüfungen für redaktionelle Rollen zugänglich machen
• Dokumentationsänderungen nachvollziehbar mit Produktänderungen und Releases koppeln

Seminarinhalte

Schritt 1: Rollen und Arbeitsgegenstände abgrenzen

Autorenschaft, fachliche Prüfung, redaktionelle Prüfung, technische Betreuung und Veröffentlichung erhalten klare Verantwortlichkeiten. Für kleine Korrekturen und größere Strukturänderungen werden unterschiedliche Wege vorgesehen.

• Rollen und Entscheidungskompetenzen beschreiben
• Änderungstypen nach Umfang und Risiko klassifizieren
• Vertretung und Eskalation festlegen

Schritt 2: Repository-Struktur für Redaktion gestalten

Ordner, Dateinamen, Assets und gemeinsame Komponenten werden so organisiert, dass Inhalte leicht auffindbar und Änderungen lokal begrenzt bleiben. Generierte Dateien und redaktionelle Quellen werden eindeutig getrennt.

• Inhaltsbereiche und Eigentümerschaft abbilden
• Asset- und Komponentenablage standardisieren
• generierte Inhalte vor manueller Bearbeitung schützen

Schritt 3: Anforderung und Planung standardisieren

Neue Inhalte beginnen mit einer nachvollziehbaren Anforderung, Zielgruppe, Aufgabe und Abnahmekriterium. Vorlagen verhindern, dass technische Umsetzung startet, bevor Zweck und Umfang geklärt sind.

• Issue-Vorlagen für neue, geänderte und veraltete Inhalte erstellen
• Akzeptanzkriterien und zuständige Prüfer festhalten
• Abhängigkeiten zu Produktänderungen markieren

Schritt 4: Lokale Autorenerfahrung vereinfachen

Installation, Start und Vorschau werden mit wenigen dokumentierten Befehlen reproduzierbar. Häufige Fehler erhalten verständliche Diagnosehinweise und optionale Entwicklungsumgebungen reduzieren lokale Unterschiede.

• Einrichtungsschritte und Laufzeitversionen festlegen
• Vorschau und produktionsnahen Build unterscheiden
• Fehlerbehebung für typische MDX- und Pfadprobleme dokumentieren

Schritt 5: Inhaltsvorlagen und Konventionen einsetzen

Vorlagen geben Struktur, Metadaten, Hinweise und Qualitätskriterien für wiederkehrende Inhaltstypen vor. Die Konventionen bleiben kurz, prüfbar und direkt an konkreten Beispielen erläutert.

• Vorlagen für Tutorial, Aufgabe, Konzept und Detailseite entwickeln
• Front-Matter-Felder und Benennungen vereinheitlichen
• zulässige MDX-Komponenten katalogisieren

Schritt 6: Branch- und Änderungsmodell festlegen

Der Arbeitsfluss wird an Veröffentlichungsfrequenz und Teamgröße angepasst. Kleine Änderungen bleiben schnell, während riskante Umbauten über getrennte Vorschauen und zusätzliche Freigaben abgesichert werden.

• kurzlebige Branches und Änderungsanträge verwenden
• Konflikt- und Zusammenführungsregeln definieren
• große Migrationen in überprüfbare Schritte zerlegen

Schritt 7: Review und Qualitätsgates verbinden

Automatisierte Prüfungen liefern technische Sicherheit, fachliche und redaktionelle Reviews bewerten Inhalt und Verständlichkeit. Review-Vorlagen lenken die Aufmerksamkeit auf Zielgruppe, Vollständigkeit und Auswirkungen.

• Prüfer nach Inhaltsbereich automatisch zuordnen
• fachliche, redaktionelle und technische Prüfpunkte trennen
• blockierende Befunde und Empfehlungen kennzeichnen

Schritt 8: Freigabe, Release und Pflege organisieren

Dokumentationsänderungen werden mit dem passenden Produktstand veröffentlicht und erhalten eine Pflegeverantwortung. Nach dem Release folgen Stichprobe, Aktualitätskontrolle und ein geregelter Umgang mit Rückmeldungen.

• Release-Kriterien und Veröffentlichungsfenster definieren
• Inhaltsstatus und Prüffrist hinterlegen
• Rückmeldungen in priorisierte Pflegeaufgaben überführen

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.

• Entwurf eines Rollen- und Workflow-Modells vom Issue bis zur Veröffentlichung
• Erstellung von Inhalts-, Änderungs- und Review-Vorlagen für ein Docusaurus-Repository
• Aufbau eines Änderungsantrags mit Vorschau, automatisierten Prüfungen und Freigaberegeln

Zielgruppe und Voraussetzungen

Zielgruppe: Technische Redaktionen, Documentation Engineers, Entwicklerteams, Product Owner und Verantwortliche für Dokumentationsprozesse

Voraussetzungen: Grundkenntnisse in Docusaurus und Markdown; grundlegender Umgang mit Git ist hilfreich und wird im Prozesskontext vertieft