Seminar PlantUML Governance, Konventionen und Diagramm-Reviews

Wachsende Diagrammbestände benötigen verbindliche Regeln für Benennung, Struktur, Qualität und Pflege. Das Seminar entwickelt eine praxistaugliche Governance, die Orientierung schafft, ohne Teams durch übermäßige Vorgaben auszubremsen.

Inhaltsverzeichnis

• Zielgruppe
• Voraussetzungen
• Lernziele
• Kapitel 1: Ziele, Geltungsbereich und Rollen
• Kapitel 2: Konventionen und Vorlagen
• Kapitel 3: Review-Systematik
• Kapitel 4: Automatisierung und Pflege
• Durchgängiges Praxisprojekt
• Methodik

Zielgruppe

Architekturverantwortliche, technische Redaktionen, Lead Developers, Plattformteams, Qualitätsmanagement und Verantwortliche für unternehmensweite Dokumentationsstandards.

Voraussetzungen

Erfahrung mit mehreren PlantUML-Diagrammen oder einem bestehenden Diagramm-Repository. Grundkenntnisse in Versionsverwaltung und Review-Prozessen.

Lernziele

• verbindliche und überprüfbare Konventionen für Diagrammquellen definieren
• Qualitätskriterien nach Diagrammtyp und Zielgruppe differenzieren
• Reviews effizient vorbereiten, durchführen und dokumentieren
• Verantwortung, Lebenszyklus und Ausnahmen eindeutig regeln
• Governance mit automatisierbaren Prüfungen und Vorlagen unterstützen

Kapitel 1: Ziele, Geltungsbereich und Rollen

Das Kapitel verbindet vier aufeinander aufbauende Arbeitsschritte: betroffene Teams, Repositories und Diagrammarten erfassen, Qualitätsziele und Mindestanforderungen festlegen, Owner, Reviewer und Freigabeverantwortung zuordnen sowie Ausnahmen und Eskalationswege definieren. Die Inhalte werden an einem nachvollziehbaren Beispiel aufgebaut, unmittelbar gerendert und anhand der fachlichen Aussage bewertet.

1. Schritt 1 – Analysieren: betroffene Teams, Repositories und Diagrammarten erfassen.
2. Schritt 2 – Modellieren: Qualitätsziele und Mindestanforderungen festlegen.
3. Schritt 3 – Erweitern: Owner, Reviewer und Freigabeverantwortung zuordnen.
4. Schritt 4 – Prüfen: Ausnahmen und Eskalationswege definieren.

Praxisübung

Für den Schwerpunkt „Ziele, Geltungsbereich und Rollen“ entsteht ein eigenständiges Teilmodell. Anschließend werden Syntax, Semantik, Lesbarkeit und Anschlussfähigkeit an das Gesamtprojekt mit einer kompakten Prüfliste kontrolliert.

Kapitel 2: Konventionen und Vorlagen

Das Kapitel verbindet vier aufeinander aufbauende Arbeitsschritte: Dateinamen, Verzeichnisse und IDs standardisieren, Benennung von Elementen und Beziehungen vereinheitlichen, Style-, Include- und Makroregeln festschreiben sowie Vorlagen für häufige Diagrammtypen bereitstellen. Die Inhalte werden an einem nachvollziehbaren Beispiel aufgebaut, unmittelbar gerendert und anhand der fachlichen Aussage bewertet.

1. Schritt 1 – Analysieren: Dateinamen, Verzeichnisse und IDs standardisieren.
2. Schritt 2 – Modellieren: Benennung von Elementen und Beziehungen vereinheitlichen.
3. Schritt 3 – Erweitern: Style-, Include- und Makroregeln festschreiben.
4. Schritt 4 – Prüfen: Vorlagen für häufige Diagrammtypen bereitstellen.

Praxisübung

Für den Schwerpunkt „Konventionen und Vorlagen“ entsteht ein eigenständiges Teilmodell. Anschließend werden Syntax, Semantik, Lesbarkeit und Anschlussfähigkeit an das Gesamtprojekt mit einer kompakten Prüfliste kontrolliert.

Kapitel 3: Review-Systematik

Das Kapitel verbindet vier aufeinander aufbauende Arbeitsschritte: fachliche, semantische und visuelle Prüfung trennen, Review-Fragen nach Zielgruppe und Diagrammtyp formulieren, Feststellungen priorisieren und nachvollziehbar dokumentieren sowie Freigabe und Wiedervorlage mit klaren Kriterien steuern. Die Inhalte werden an einem nachvollziehbaren Beispiel aufgebaut, unmittelbar gerendert und anhand der fachlichen Aussage bewertet.

1. Schritt 1 – Analysieren: fachliche, semantische und visuelle Prüfung trennen.
2. Schritt 2 – Modellieren: Review-Fragen nach Zielgruppe und Diagrammtyp formulieren.
3. Schritt 3 – Erweitern: Feststellungen priorisieren und nachvollziehbar dokumentieren.
4. Schritt 4 – Prüfen: Freigabe und Wiedervorlage mit klaren Kriterien steuern.

Praxisübung

Für den Schwerpunkt „Review-Systematik“ entsteht ein eigenständiges Teilmodell. Anschließend werden Syntax, Semantik, Lesbarkeit und Anschlussfähigkeit an das Gesamtprojekt mit einer kompakten Prüfliste kontrolliert.

Kapitel 4: Automatisierung und Pflege

Das Kapitel verbindet vier aufeinander aufbauende Arbeitsschritte: maschinenprüfbare Regeln von manuellen Regeln unterscheiden, Syntax-, Pfad- und Richtlinienprüfungen integrieren, veraltete Diagramme und Eigentümerwechsel erkennen sowie Konventionen anhand realer Rückmeldungen versioniert weiterentwickeln. Die Inhalte werden an einem nachvollziehbaren Beispiel aufgebaut, unmittelbar gerendert und anhand der fachlichen Aussage bewertet.

1. Schritt 1 – Analysieren: maschinenprüfbare Regeln von manuellen Regeln unterscheiden.
2. Schritt 2 – Modellieren: Syntax-, Pfad- und Richtlinienprüfungen integrieren.
3. Schritt 3 – Erweitern: veraltete Diagramme und Eigentümerwechsel erkennen.
4. Schritt 4 – Prüfen: Konventionen anhand realer Rückmeldungen versioniert weiterentwickeln.

Praxisübung

Für den Schwerpunkt „Automatisierung und Pflege“ entsteht ein eigenständiges Teilmodell. Anschließend werden Syntax, Semantik, Lesbarkeit und Anschlussfähigkeit an das Gesamtprojekt mit einer kompakten Prüfliste kontrolliert.

Durchgängiges Praxisprojekt

Aus einem uneinheitlichen Beispielbestand entstehen eine kompakte Konventionssammlung, zwei Diagrammvorlagen, eine Review-Checkliste und ein Plan für automatisierbare Prüfungen.

Methodik

Fachimpulse, Live-Coding, kommentierte Demonstrationen und schrittweise Übungen wechseln sich ab. Jede neue Technik wird zunächst an einem Minimalbeispiel geprüft, danach in das Gesamtprojekt übernommen und abschließend in einem strukturierten Review bewertet. Alle Übungen verwenden versionierbare Textquellen und reproduzierbare Render-Schritte.