Seminar Mermaid Dokumentation als Code mit Markdown und Git

Seminarprofil: Diagramme werden als versionierte Textquellen in Markdown-Dokumentationen eingebettet und über Git nachvollziehbar gepflegt. Die Inhalte werden anhand eines durchgängigen Fachszenarios schrittweise aufgebaut, unmittelbar geprüft und in einem zusammenhängenden Praxisprojekt angewendet.

Inhaltsübersicht

Inhaltsverzeichnis dieses Kapitels: Seminarprofil, Zielsetzung, Zielgruppe, Voraussetzungen, Seminarinhalte, Praxisprojekt und Arbeitsmethoden.

1. Zielsetzung und Kompetenzaufbau
2. Zielgruppe und fachliche Einordnung
3. Voraussetzungen und Arbeitsumgebung
4. Schrittweise Seminarinhalte nach Tagen
5. Durchgängiges Praxisprojekt
6. Arbeits- und Prüfmethoden

Zielsetzung

Inhaltsverzeichnis dieses Kapitels: Fachkompetenz, Umsetzungskompetenz, Qualitätskontrolle und nachhaltige Pflege.

Nach der Bearbeitung können die behandelten Mermaid-Funktionen nicht nur syntaktisch verwendet, sondern fachlich begründet ausgewählt und in einen geregelten Dokumentationsprozess eingebettet werden. Im Mittelpunkt stehen folgende Kompetenzen:

• Dokumentations- und Diagrammquellen sinnvoll strukturieren
• Änderungen gemeinsam mit Texten versionieren
• Reviews für fachliche und visuelle Qualität durchführen
• Veröffentlichungen reproduzierbar vorbereiten

Zielgruppe

Inhaltsverzeichnis dieses Kapitels: Geeignete Rollen, typische Aufgabenstellungen und gemeinsamer Anwendungskontext.

Technische Redaktion, Softwareentwicklung, DevOps, Architektur, Produktdokumentation und Wissensmanagement. Das Seminar ist auf die gemeinsame Bearbeitung realer Modellierungs- und Dokumentationsaufgaben ausgerichtet.

Voraussetzungen

Inhaltsverzeichnis dieses Kapitels: Fachwissen, technische Vorkenntnisse und benötigte Arbeitsmittel.

Grundkenntnisse in Markdown und Git sind hilfreich; Mermaid-Grundlagen werden kurz wiederholt. Für die Übungen wird eine textbasierte Arbeitsumgebung mit Vorschau verwendet; alle Arbeitsschritte bleiben auch ohne spezielle Vorerfahrungen nachvollziehbar.

Seminarinhalte

Inhaltsverzeichnis dieses Kapitels: Tag 1: Dokumentationsstruktur und eingebettete Diagramme, Tag 2: Versionskontrolle, Review und Veröffentlichung.

Tag 1: Dokumentationsstruktur und eingebettete Diagramme

Inhaltsverzeichnis dieses Kapitels: Informationsarchitektur und Verzeichnisstruktur festlegen, Mermaid-Blöcke in Markdown einbetten, Dateinamen und Diagrammkennungen vereinheitlichen, Text und Diagramm inhaltlich synchron halten, Lokale Vorschau und Ausgabe kontrollieren.

Der erste Tag baut einen klar gegliederten Docs-as-Code-Bestand mit wiederauffindbaren Diagrammquellen auf. Jeder Themenbaustein wird zunächst fachlich eingeordnet, anschließend im Code umgesetzt und danach anhand definierter Qualitätskriterien kontrolliert.

1. Schritt 1: Informationsarchitektur und Verzeichnisstruktur festlegen
   Zunächst werden Zweck, Begriffe und notwendige Abgrenzungen geklärt. Danach entsteht eine kleine, überprüfbare Grundfassung im Mermaid-Code. Die Aussage wird gegen das zugrunde liegende Fachszenario geprüft.
   Praxisaufgabe: Für den Baustein „Informationsarchitektur und Verzeichnisstruktur festlegen“ wird eine eigene Variante erstellt, gerendert, mit mindestens einer Alternative verglichen und anhand der Seminarkriterien überarbeitet.
2. Schritt 2: Mermaid-Blöcke in Markdown einbetten
   Die Grundstruktur wird schrittweise erweitert. Jede Änderung wird unmittelbar gerendert und auf Syntax, Beziehungsaussage und unerwünschte Nebenwirkungen kontrolliert.
   Praxisaufgabe: Für den Baustein „Mermaid-Blöcke in Markdown einbetten“ wird eine eigene Variante erstellt, gerendert, mit mindestens einer Alternative verglichen und anhand der Seminarkriterien überarbeitet.
3. Schritt 3: Dateinamen und Diagrammkennungen vereinheitlichen
   Das Modell wird um realistische Varianten, Ausnahmen und Detailinformationen ergänzt. Dabei bleibt sichtbar, welche Information für die jeweilige Zielgruppe notwendig ist und welche besser ausgelagert wird.
   Praxisaufgabe: Für den Baustein „Dateinamen und Diagrammkennungen vereinheitlichen“ wird eine eigene Variante erstellt, gerendert, mit mindestens einer Alternative verglichen und anhand der Seminarkriterien überarbeitet.
4. Schritt 4: Text und Diagramm inhaltlich synchron halten
   Mehrere Darstellungsvarianten werden verglichen. Lesbarkeit, semantische Eindeutigkeit, Wartbarkeit und stabile Ausgabe bilden die verbindlichen Auswahlkriterien.
   Praxisaufgabe: Für den Baustein „Text und Diagramm inhaltlich synchron halten“ wird eine eigene Variante erstellt, gerendert, mit mindestens einer Alternative verglichen und anhand der Seminarkriterien überarbeitet.
5. Schritt 5: Lokale Vorschau und Ausgabe kontrollieren
   Der Baustein wird in einen wiederverwendbaren Arbeitsprozess überführt. Benennung, Ablage, Prüfung und spätere Änderung werden so festgelegt, dass das Diagramm dauerhaft gepflegt werden kann.
   Praxisaufgabe: Für den Baustein „Lokale Vorschau und Ausgabe kontrollieren“ wird eine eigene Variante erstellt, gerendert, mit mindestens einer Alternative verglichen und anhand der Seminarkriterien überarbeitet.

Tagesaufgabe: Eine kleine technische Dokumentation mit mehreren Diagrammtypen, Namensregeln und nachvollziehbarer Ablagestruktur anlegen.

Tag 2: Versionskontrolle, Review und Veröffentlichung

Inhaltsverzeichnis dieses Kapitels: Änderungen in fachlich kleine Commits schneiden, Branches und Review-Schritte definieren, Diagrammänderungen im Vergleich beurteilen, Build- und Freigaberegeln festlegen, Pflege, Archivierung und Verantwortlichkeiten organisieren.

Der zweite Tag integriert die Dokumentation in einen geregelten Änderungs- und Veröffentlichungsprozess. Jeder Themenbaustein wird zunächst fachlich eingeordnet, anschließend im Code umgesetzt und danach anhand definierter Qualitätskriterien kontrolliert.

1. Schritt 1: Änderungen in fachlich kleine Commits schneiden
   Zunächst werden Zweck, Begriffe und notwendige Abgrenzungen geklärt. Danach entsteht eine kleine, überprüfbare Grundfassung im Mermaid-Code. Die Aussage wird gegen das zugrunde liegende Fachszenario geprüft.
   Praxisaufgabe: Für den Baustein „Änderungen in fachlich kleine Commits schneiden“ wird eine eigene Variante erstellt, gerendert, mit mindestens einer Alternative verglichen und anhand der Seminarkriterien überarbeitet.
2. Schritt 2: Branches und Review-Schritte definieren
   Die Grundstruktur wird schrittweise erweitert. Jede Änderung wird unmittelbar gerendert und auf Syntax, Beziehungsaussage und unerwünschte Nebenwirkungen kontrolliert.
   Praxisaufgabe: Für den Baustein „Branches und Review-Schritte definieren“ wird eine eigene Variante erstellt, gerendert, mit mindestens einer Alternative verglichen und anhand der Seminarkriterien überarbeitet.
3. Schritt 3: Diagrammänderungen im Vergleich beurteilen
   Das Modell wird um realistische Varianten, Ausnahmen und Detailinformationen ergänzt. Dabei bleibt sichtbar, welche Information für die jeweilige Zielgruppe notwendig ist und welche besser ausgelagert wird.
   Praxisaufgabe: Für den Baustein „Diagrammänderungen im Vergleich beurteilen“ wird eine eigene Variante erstellt, gerendert, mit mindestens einer Alternative verglichen und anhand der Seminarkriterien überarbeitet.
4. Schritt 4: Build- und Freigaberegeln festlegen
   Mehrere Darstellungsvarianten werden verglichen. Lesbarkeit, semantische Eindeutigkeit, Wartbarkeit und stabile Ausgabe bilden die verbindlichen Auswahlkriterien.
   Praxisaufgabe: Für den Baustein „Build- und Freigaberegeln festlegen“ wird eine eigene Variante erstellt, gerendert, mit mindestens einer Alternative verglichen und anhand der Seminarkriterien überarbeitet.
5. Schritt 5: Pflege, Archivierung und Verantwortlichkeiten organisieren
   Der Baustein wird in einen wiederverwendbaren Arbeitsprozess überführt. Benennung, Ablage, Prüfung und spätere Änderung werden so festgelegt, dass das Diagramm dauerhaft gepflegt werden kann.
   Praxisaufgabe: Für den Baustein „Pflege, Archivierung und Verantwortlichkeiten organisieren“ wird eine eigene Variante erstellt, gerendert, mit mindestens einer Alternative verglichen und anhand der Seminarkriterien überarbeitet.

Tagesaufgabe: Einen vollständigen Änderungsweg vom Arbeitszweig über Review und Prüfung bis zum freigegebenen Dokumentationsstand durchführen.

Praxisprojekt

Inhaltsverzeichnis dieses Kapitels: Aufgabenanalyse, Modellierungsentscheidung, schrittweise Umsetzung, Prüfung und dokumentierter Endstand.

Ein versionierter Docs-as-Code-Bestand mit Markdown, mehreren Mermaid-Diagrammen, Strukturregeln, Review-Verfahren und reproduzierbarer Veröffentlichung. Das Projekt wird in klar abgegrenzte Arbeitsschritte zerlegt. Nach jedem Schritt werden Syntax, fachliche Aussage, visuelle Lesbarkeit und spätere Änderbarkeit kontrolliert. Der Endstand enthält neben den Diagrammen auch Benennungs-, Struktur- und Prüfregeln.

Arbeitsmethoden

Inhaltsverzeichnis dieses Kapitels: Demonstration, angeleitete Umsetzung, Variantenvergleich, Fehleranalyse und eigenständige Vertiefung.

Kurze fachliche Einführungen wechseln mit Live-Demonstrationen und unmittelbar anschließenden Übungen. Komplexe Diagramme werden nicht als fertige Lösung präsentiert, sondern in kleinen, prüfbaren Änderungen aufgebaut. Varianten werden gegeneinander bewertet; typische Fehlbilder werden bewusst erzeugt, eingegrenzt und korrigiert. Das Praxisprojekt verbindet alle Kapitel zu einem konsistenten Arbeitsstand.