Seminar Kroki – Intensivseminar: Diagrammsprachen und Dokumentationsworkflows

Vom ersten Diagramm zur konsistenten Diagrammlandschaft

Das Intensivseminar bündelt die fachlichen Inhalte der Grundlagen-, Sprach-, Migrations-, Dokumentations- und Governance-Seminare. Es vermittelt einen breiten, praxisfähigen Überblick, ersetzt jedoch nicht jede spezialisierte Vertiefung in voller Tiefe. Die Auswahl konzentriert sich auf typische Architektur-, Prozess-, Daten-, Netzwerk-, Hardware- und Dokumentationsaufgaben.

Fünf Tage sind die maximal sinnvolle Kompaktdauer für diesen Umfang. Jeder Tag verbindet Sprachkonzepte, Kroki-Rendering und Qualitätsprüfung. Ein gemeinsames Beispielszenario wird schrittweise erweitert, sodass isolierte Syntaxübungen zu einer konsistenten Diagrammlandschaft zusammenwachsen.

Inhaltsübersicht

• Kroki-Grundlagen, API und Auswahl geeigneter Notationen
• PlantUML, C4 und Structurizr für Softwarearchitektur
• Mermaid, BPMN und Excalidraw für Abläufe und Fachprozesse
• GraphViz, D2 und ERD für Graphen und Datenmodelle
• Netzwerk-, Hardware-, Text- und ASCII-Diagramme
• Vega und Vega-Lite für deklarative Datenvisualisierung
• AsciiDoc, Markdown, GitLab und Sphinx
• Migration, Teamstandards, Review und Abschlussprojekt

Zielgruppe

Das Seminar richtet sich an Architekten, Entwickler, technische Redakteure, Analysten, Administratoren und fachübergreifende Teams, die ein breites Kroki-Kompetenzprofil in kurzer Zeit aufbauen möchten. Für reine Plattformadministration ist das separate Intensivseminar zum Plattformbetrieb zielgerichteter.

Voraussetzungen

Erforderlich sind allgemeine IT-Kenntnisse, Grundkenntnisse der Versionsverwaltung und Bereitschaft zur Arbeit mit textuellen Quellen. Erfahrungen mit Softwarearchitektur, Datenmodellen oder Dokumentationssystemen sind hilfreich, aber nicht für alle Themen zwingend.

Lernstrecke Schritt für Schritt

1. Schritt 1: Ziele, Diagrammarten und Qualitätskriterien festlegen. Das gemeinsame Fallbeispiel wird analysiert. Architektur, Ablauf, Daten, Netzwerk, Hardware und Kennzahlen erhalten getrennte Fragestellungen und Zielgruppen.
2. Schritt 2: Kroki-API und Ausgabewege anwenden. Klartext- und JSON-POST, kodierte GET-Anfragen, Formate und Optionen werden praktisch genutzt. Ein einheitliches Request-Muster gilt für alle folgenden Sprachen.
3. Schritt 3: PlantUML-Grundmodelle erstellen. Komponenten, Sequenzen, Zustände und Deployment-Strukturen werden als Text beschrieben. Beziehungen und Begriffe folgen einem gemeinsamen Glossar.
4. Schritt 4: C4 und Structurizr einsetzen. Kontext-, Container- und ausgewählte Komponentenansichten werden aus abgestimmten Modellelementen erzeugt. Die Ebenen bleiben klar voneinander getrennt.
5. Schritt 5: Mermaid für technische Abläufe nutzen. Flowcharts, Sequenzen, Zustände und Zeitpläne werden auf typische Einsatzgrenzen geprüft. Diagrammoptionen und Companion-Betrieb werden einbezogen.
6. Schritt 6: BPMN und Excalidraw einordnen. Fachprozesse erhalten eine formale BPMN-Sicht; freiere Skizzen werden mit Excalidraw-Daten gerendert. Aussage und Änderbarkeit bestimmen die Wahl.
7. Schritt 7: GraphViz und D2 für Abhängigkeiten verwenden. Ein technischer Abhängigkeitsgraph und eine strukturierte Systemübersicht werden erstellt. Layout, Cluster und Komplexitätsgrenzen werden kontrolliert.
8. Schritt 8: ERD für Datenstrukturen modellieren. Entitäten, Attribute, Schlüssel und Kardinalitäten werden aus dem Fallbeispiel abgeleitet und mit Architekturbegriffen abgeglichen.
9. Schritt 9: Netzwerk- und Paketdarstellungen ergänzen. Netzwerkzonen, Geräte, Paketfelder oder Rackbezüge werden mit geeigneten Spezialsprachen beschrieben. Technische Details bleiben in eigenen Sichten.
10. Schritt 10: Hardware- und Timingdiagramme anwenden. Ein kleines Register- oder Signalbeispiel zeigt Bytefield, WaveDrom, Symbolator oder WireViz. Die Auswahl richtet sich nach vorhandenen Fachanforderungen.
11. Schritt 11: Text- und ASCII-Werkzeuge vergleichen. Ditaa, SvgBob, GoAT und Pikchr werden für schnelle technische Skizzen erprobt. Lesbarkeit der Quelle und Stabilität des Layouts werden bewertet.
12. Schritt 12: Daten mit Vega-Lite visualisieren. Eine Kennzahl wird aus strukturierten Daten mit Mark, Encoding, Skala und Beschriftung dargestellt. Transformation und Aussage bleiben nachvollziehbar.
13. Schritt 13: Diagramme in Dokumentation integrieren. AsciiDoc-, Markdown-, GitLab- oder Sphinx-Workflows binden Quellen und gerenderte Ausgaben ein. Lokale Vorschau und CI-Build werden abgestimmt.
14. Schritt 14: Bestände migrieren und Standards definieren. Vorhandene Bilder werden priorisiert, Zielsprachen zugeordnet und nach Namens-, Stil- und Reviewregeln überführt. Zugänglichkeit und Textalternativen werden berücksichtigt.
15. Schritt 15: Das Abschlussprojekt konsolidieren. Mehrere Sichten werden gerendert, in eine Dokumentation eingebunden und durch ein fachliches sowie technisches Review geführt. Inkonsistenzen werden vor der Freigabe korrigiert.

Praxisaufgaben

• Ein gemeinsames System in Architektur-, Ablauf-, Daten- und Betriebssichten zerlegen.
• Mindestens fünf unterschiedliche Diagrammsprachen über dasselbe Kroki-Anfragemodell rendern.
• Eine Dokumentationsseite mit versionierten Quellen und automatisierter Erzeugung aufbauen.
• Ein vorhandenes manuelles Diagramm in eine geeignete Textnotation migrieren.
• Eine komplette Diagrammlandschaft mit Glossar, Reviewcheckliste und Freigabestand erstellen.

Kompetenzziele

• Kroki übergreifend für unterschiedliche Diagrammsprachen einsetzen.
• Notation, Abstraktion und Ausgabeformat nach fachlicher Aufgabe auswählen.
• Architektur-, Prozess-, Daten-, Netzwerk-, Hardware- und Kennzahlensichten erstellen.
• Diagramme in versionierte Dokumentations- und Build-Prozesse integrieren.
• Migration, Teamstandards und Qualitätsreviews für eine konsistente Diagrammlandschaft organisieren.