Seminar Kroki – Text- und ASCII-Diagramme mit Ditaa, SvgBob, GoAT und Pikchr

Skizzen und technische Formen direkt aus Text erzeugen

ASCII-nahe Diagrammsprachen eignen sich für schnelle Skizzen, README-Dateien und technische Darstellungen, deren Quelle unmittelbar lesbar bleiben soll. Ditaa, SvgBob, GoAT und Pikchr unterscheiden sich jedoch deutlich bei Syntax, Layoutkontrolle und Stabilität.

Zwei Tage sind notwendig, um vier Werkzeuge praktisch zu vergleichen, Zeichensatz- und Formatierungsprobleme zu beherrschen und aus einer spontanen Skizze eine reproduzierbare, reviewfähige Dokumentationsquelle zu entwickeln.

Inhaltsübersicht

• Einsatzgrenzen text- und ASCII-naher Diagramme
• Ditaa für Boxen, Verbindungen und einfache Strukturen
• SvgBob für technische ASCII-Zeichnungen
• GoAT für textbasierte Diagrammskizzen
• Pikchr für präziser platzierte Formen und Beziehungen
• Zeichensatz, Monospace und stabile Quellformatierung
• Kroki-Rendering und Dokumentationsintegration
• Werkzeugvergleich, Review und Fallstudie

Zielgruppe

Das Seminar richtet sich an Entwickler, Administratoren, technische Redakteure, Architekten und Open-Source- oder Plattformteams, die kompakte Diagramme direkt in textnahen Quellen pflegen möchten.

Voraussetzungen

Erforderlich sind allgemeine IT-Kenntnisse und sicherer Umgang mit Textdateien. Erfahrung mit Markdown, AsciiDoc oder README-Dokumentation ist hilfreich. Vorkenntnisse in Ditaa, SvgBob, GoAT oder Pikchr werden nicht vorausgesetzt.

Lernstrecke Schritt für Schritt

1. Schritt 1: Eignung textnaher Diagramme bewerten. Quelllesbarkeit, Layoutanspruch, Zielmedium, Änderungsrate und benötigte Semantik bestimmen, ob eine ASCII-nahe Sprache sinnvoll ist.
2. Schritt 2: Ein Ditaa-Grunddiagramm erstellen. Boxen, Linien, Pfeile, Beschriftungen und grundlegende Typkennzeichnungen werden in einem festen Zeichenraster aufgebaut.
3. Schritt 3: Ditaa-Strukturen stabilisieren. Ausrichtung, Abstände und Verbindungspunkte werden so formatiert, dass kleine Textänderungen nicht unbeabsichtigt das gesamte Layout zerstören.
4. Schritt 4: SvgBob anwenden. Technische Skizzen, Leitungen, Pfeile und Formen werden aus ASCII-Quellen erzeugt. Eignung für README- und Protokolldokumentation wird geprüft.
5. Schritt 5: GoAT vergleichen. Ein identisches Beispiel wird mit GoAT umgesetzt. Quelllesbarkeit, unterstützte Formen und Renderstabilität werden systematisch verglichen.
6. Schritt 6: Pikchr-Grundlagen nutzen. Formen, relative Positionen, Verbindungen und Beschriftungen werden präziser als in reinem ASCII angeordnet.
7. Schritt 7: Komplexere Pikchr-Strukturen aufbauen. Wiederholte Elemente, Ausrichtung und Gruppen werden für eine technische Komponentenübersicht verwendet.
8. Schritt 8: Zeichensatz und Whitespace kontrollieren. UTF-8, Tabulatoren, Leerzeichen, Zeilenenden und Monospace-Darstellung werden vereinheitlicht. Automatische Formatierer werden passend konfiguriert.
9. Schritt 9: Quellenkonventionen definieren. Maximale Breite, Einrückung, Kommentare, Beschriftung und Dateiendungen erhalten einfache Regeln.
10. Schritt 10: Über Kroki rendern. Diagrammtyp, Quelle und Ausgabeformat werden per API oder CLI verarbeitet. Fehlermeldungen werden von Quellformatierungsproblemen getrennt.
11. Schritt 11: In Dokumentation integrieren. Eine textnahe Quelle wird in Markdown oder AsciiDoc eingebunden und im automatisierten Build gerendert.
12. Schritt 12: Werkzeuge anhand einer Fallstudie auswählen. Vier Varianten derselben technischen Skizze werden nach Aussage, Quelllesbarkeit, Layoutstabilität und Wartungsaufwand bewertet.

Praxisaufgaben

• Eine kleine Systemskizze mit Ditaa erstellen und stabil ausrichten.
• Dasselbe Beispiel mit SvgBob oder GoAT umsetzen und vergleichen.
• Eine präzise technische Darstellung mit Pikchr aufbauen.
• Whitespace- und Zeichensatzfehler absichtlich erzeugen und beheben.
• Eine textnahe Diagrammquelle in einen automatisierten Dokumentationsbuild integrieren.

Kompetenzziele

• Text- und ASCII-nahe Diagrammsprachen nach Einsatzfall auswählen.
• Ditaa, SvgBob, GoAT und Pikchr für typische technische Skizzen verwenden.
• Zeichensatz, Whitespace und Layoutquellen stabil organisieren.
• Textdiagramme über Kroki reproduzierbar rendern und integrieren.
• Werkzeuge anhand von Lesbarkeit, Aussage und Wartungsaufwand bewerten.