Seminar Kroki – Grundlagen und erste Diagramme

Textbasierte Diagramme verstehen und sicher erzeugen

Kroki wandelt textuelle Diagrammbeschreibungen über eine einheitliche Schnittstelle in Bilder um. Dadurch werden Diagramme versionierbar, wiederholbar und gemeinsam mit Quellcode oder Dokumentation pflegbar. Das Seminar vermittelt den vollständigen Einstieg ohne vorausgesetzte Erfahrung mit Diagrammsprachen.

Der eintägige Umfang ist für einen fundierten Überblick mit mehreren kleinen Übungen ausreichend. Vertiefte Sprachsyntax, Plattformbetrieb und Automatisierung werden bewusst nur eingeordnet und sind Gegenstand der weiterführenden Seminare.

Inhaltsübersicht

• Grundidee von Diagrams as Code und Rolle von Kroki
• Öffentlicher Dienst und selbst verwaltete Instanz
• Auswahl von Diagrammtyp und Sprache
• Erste Quellen mit GraphViz, PlantUML und Mermaid
• GET- und POST-Aufrufe in Grundform
• SVG, PNG und weitere Ausgabeformate
• Ablage, Benennung und Versionsverwaltung
• Fehlersuche und kleiner Praxisworkflow

Zielgruppe

Das Seminar richtet sich an Entwickler, Administratoren, Architekten, technische Redakteure, Analysten und Projektmitarbeiter, die Diagramme aus Text erzeugen oder bestehende Dokumentationsabläufe modernisieren möchten.

Voraussetzungen

Erforderlich sind allgemeine IT-Kenntnisse und sicherer Umgang mit Dateien. Grundkenntnisse der Kommandozeile sind hilfreich, aber nicht zwingend. Programmierkenntnisse oder Erfahrung mit PlantUML, Mermaid und GraphViz werden nicht vorausgesetzt.

Lernstrecke Schritt für Schritt

1. Schritt 1: Diagrams as Code einordnen. Manuell gezeichnete Bilder und textbasierte Quellen werden hinsichtlich Änderbarkeit, Review, Versionierung und Reproduzierbarkeit verglichen.
2. Schritt 2: Kroki-Funktionsprinzip verstehen. Diagrammquelle, Diagrammtyp, Ausgabeformat und Rendering-Dienst werden als getrennte Bausteine betrachtet. Öffentlicher und selbst verwalteter Betrieb werden abgegrenzt.
3. Schritt 3: Eine geeignete Diagrammsprache auswählen. Ablauf, Architektur, Datenmodell, Netzwerk und freie Skizze werden unterschiedlichen Sprachfamilien zugeordnet. Auswahlkriterien ersetzen die Suche nach einer einzigen Universalsprache.
4. Schritt 4: Ein erstes GraphViz-Diagramm erstellen. Knoten und gerichtete Beziehungen bilden einen kleinen Prozess ab. Die Textquelle wird gerendert, verändert und erneut erzeugt.
5. Schritt 5: Ein erstes PlantUML-Diagramm erstellen. Akteure, Komponenten oder Nachrichten werden mit wenigen Sprachelementen beschrieben. Syntaxfehler und deren Rückmeldung werden nachvollzogen.
6. Schritt 6: Ein erstes Mermaid-Diagramm erstellen. Ein Ablauf oder eine Sequenz wird als Mermaid-Quelle formuliert. Die benötigte Companion-Unterstützung wird funktional eingeordnet.
7. Schritt 7: POST-Anfragen verwenden. Eine Diagrammquelle wird als Klartext oder JSON übertragen. Diagrammtyp, Ausgabeformat und Medientyp werden eindeutig angegeben.
8. Schritt 8: GET-Anfragen einordnen. Kodierte Diagrammadressen werden erklärt und mit einem vorbereiteten Beispiel genutzt. Die vollständige Kodierung bleibt der API-Vertiefung vorbehalten.
9. Schritt 9: Ausgabeformate bewerten. SVG und Rasterformate werden nach Skalierbarkeit, Einbettung, Dateigröße und Zielmedium verglichen. Das geeignete Format wird für einen Anwendungsfall ausgewählt.
10. Schritt 10: Quellen ordentlich ablegen. Verzeichnis, Dateiendung, Benennung, Beschreibung und Versionsverwaltung werden für ein kleines Repository festgelegt.
11. Schritt 11: Fehler systematisch eingrenzen. Endpunkt, Diagrammtyp, Quellsyntax und Ausgabeformat werden in einer festen Reihenfolge geprüft. Dadurch werden zufällige Änderungen vermieden.
12. Schritt 12: Einen Mini-Workflow abschließen. Eine Dokumentationsseite erhält eine versionierte Diagrammquelle, ein gerendertes Ergebnis und eine kurze Prüfanweisung für spätere Änderungen.

Praxisaufgaben

• Dasselbe fachliche Thema als GraphViz-, PlantUML- und Mermaid-Variante skizzieren.
• Eine Quelle per POST rendern und das Ausgabeformat wechseln.
• Einen Syntaxfehler absichtlich erzeugen und anhand der Rückmeldung beheben.
• Eine sinnvolle Ordner- und Benennungsstruktur für Diagrammquellen anlegen.
• Einen kleinen Dokumentationsworkflow von der Quelle bis zur geprüften Ausgabe durchführen.

Kompetenzziele

• Kroki und Diagrams as Code fachlich einordnen.
• Für einfache Aufgaben eine geeignete Diagrammsprache auswählen.
• Erste GraphViz-, PlantUML- und Mermaid-Quellen erstellen.
• Grundlegende HTTP-Aufrufe und Ausgabeformate verwenden.
• Diagrammquellen geordnet ablegen, versionieren und Fehler systematisch beheben.