Seminar Kroki – Migration zu Diagrams as Code

Bestehende Diagrammbestände in versionierbare Quellen überführen

Die Migration zu Diagrams as Code ist keine automatische Bildkonvertierung. Bestehende Diagramme enthalten oft veraltete Aussagen, uneinheitliche Begriffe und unklare Verantwortlichkeiten. Das Seminar verbindet Inventur, fachliche Bereinigung, Auswahl einer Zielnotation und kontrollierte Ablösung.

Zwei Tage sind notwendig, weil neben der technischen Rekonstruktion auch Priorisierung, Review, Dokumentationsaustausch, Parallelbetrieb und Zuständigkeiten praktisch geplant werden. Ein repräsentativer Bestand wird während des Seminars vollständig durch die Migrationskette geführt.

Inhaltsübersicht

• Inventur von Quellen, Bildern und Einbettungen
• Bewertung nach Aktualität, Nutzen und Risiko
• Zuordnung geeigneter Kroki-Diagrammsprachen
• Begriffsbereinigung und Rekonstruktion
• Repository-, Namens- und Metadatenstruktur
• Fachliches und technisches Review
• Automatisiertes Rendering und Austausch in Dokumentationen
• Parallelbetrieb, Rollout und kontrollierte Ablösung

Zielgruppe

Das Seminar richtet sich an Architekten, technische Redakteure, Entwickler, Dokumentationsverantwortliche und Projektleiter, die Visio-, Draw.io-, Präsentations-, Wiki- oder Bildbestände in einen versionierbaren Prozess überführen möchten.

Voraussetzungen

Erforderlich sind ein repräsentativer Diagrammbestand und Grundkenntnisse der Versionsverwaltung. Kenntnisse einzelner Diagrammsprachen sind hilfreich, werden für die Sprachwahl jedoch kompakt vermittelt. Fachverantwortliche sollten für die inhaltliche Abnahme benannt sein.

Lernstrecke Schritt für Schritt

1. Schritt 1: Bestände und Fundorte inventarisieren. Quelldateien, exportierte Bilder, Dokumenteinbettungen, Wiki-Seiten und verwaiste Kopien werden erfasst. Herkunft und Änderbarkeit bleiben nachvollziehbar.
2. Schritt 2: Diagramme fachlich klassifizieren. Architektur, Ablauf, Datenmodell, Netzwerk, Hardware, Kennzahl oder freie Skizze werden unterschieden. Mischdiagramme werden in getrennte Aussagen zerlegt.
3. Schritt 3: Aktualität und Nutzen bewerten. Fachliche Gültigkeit, Nutzungshäufigkeit, Änderungsrate und Ausfallwirkung bestimmen die Priorität. Veraltete oder doppelte Darstellungen werden nicht ungeprüft migriert.
4. Schritt 4: Zielsprachen zuordnen. PlantUML, C4, Structurizr, Mermaid, BPMN, GraphViz, D2, ERD und weitere Kroki-Typen werden nach Aussage und Wartbarkeit ausgewählt.
5. Schritt 5: Ein Glossar und Benennungsregeln erstellen. Systeme, Rollen, Schnittstellen, Zustände und Technologien erhalten stabile Bezeichnungen. Synonyme und Altbegriffe werden dokumentiert oder aufgelöst.
6. Schritt 6: Eine Pilotquelle rekonstruieren. Das wichtigste Diagramm wird in der gewählten Sprache neu modelliert. Nicht sichtbare Annahmen werden als Fragen oder Begleittext offengelegt.
7. Schritt 7: Fachliche Gleichwertigkeit prüfen. Die neue Darstellung wird nicht nur optisch, sondern hinsichtlich Aussage, Vollständigkeit, Abstraktion und Zielgruppe mit dem Altbestand verglichen.
8. Schritt 8: Repository-Struktur festlegen. Quellen, generierte Ausgaben, Metadaten, Dokumentation und Tests erhalten klare Verzeichnisse und Dateinamen.
9. Schritt 9: Rendering automatisieren. Kroki-Aufrufe werden in Skript oder CI-Pipeline integriert. Änderungen an Quellen führen zu nachvollziehbaren neuen Ausgaben.
10. Schritt 10: Dokumenteinbettungen austauschen. Alte Bilder werden schrittweise durch gerenderte Artefakte oder direkte Integrationen ersetzt. Referenzen und alternative Texte bleiben gültig.
11. Schritt 11: Parallelbetrieb und Abnahme organisieren. Alt- und Neudarstellung bestehen für einen begrenzten Zeitraum nebeneinander. Fachliche Freigabe, technische Prüfung und Rückfallweg sind definiert.
12. Schritt 12: Alte Quellen kontrolliert ablösen. Freigegebene Altdateien werden archiviert oder als ersetzt gekennzeichnet. Verantwortlichkeit und Pflegezyklus der neuen Quellen werden verbindlich übergeben.

Praxisaufgaben

• Einen gemischten Diagrammbestand inventarisieren und priorisieren.
• Für mindestens fünf Diagramme geeignete Zielsprachen begründen.
• Ein manuelles Diagramm vollständig als textuelle Quelle rekonstruieren.
• Ein fachliches Review mit Abweichungs- und Klärungsliste durchführen.
• Einen Rolloutplan mit Parallelbetrieb, Abnahme und Ablösung erstellen.

Kompetenzziele

• Diagrammbestände strukturiert erfassen, bewerten und priorisieren.
• Geeignete Kroki-Sprachen nach Aussage und Wartbarkeit zuordnen.
• Manuelle Darstellungen fachlich sauber als Textquellen rekonstruieren.
• Repository, Rendering, Review und Dokumentaustausch zusammen planen.
• Parallelbetrieb und Ablösung alter Quellen kontrolliert organisieren.