Seminar Kroki – Diagramme in AsciiDoc, Markdown, GitLab und Sphinx

Diagramme direkt aus der technischen Dokumentation erzeugen

Technische Dokumentation bleibt nur dann konsistent, wenn Diagrammquelle, Text und Softwarestand gemeinsam versioniert werden. Das Seminar zeigt, wie Kroki in AsciiDoc-, Markdown-, GitLab- und Sphinx-Prozesse eingebunden wird, ohne Diagramme als manuell nachgeführte Fremddateien zu behandeln.

Zwei Tage sind notwendig, weil sich Syntax, Vorschau, Build-Prozess und Betriebsmodell der Dokumentationssysteme unterscheiden. Die Übungen verbinden lokale Bearbeitung, einen kontrollierten Kroki-Endpunkt, CI-Erzeugung und eine nachvollziehbare Veröffentlichung.

Inhaltsübersicht

• Repository- und Ordnerstruktur für Text und Diagrammquellen
• AsciiDoc-Diagrammblöcke und Vorschau
• Markdown-Integrationen und Dateireferenzen
• GitLab-Konfiguration für Kroki-Rendering
• Sphinx-Erweiterung und Dokumentationsbuild
• IDE-Unterstützung und lokale Qualitätskontrolle
• Self-Hosting, Offline-Betrieb und Endpunktwechsel
• CI-Rendering, Veröffentlichung und Fehlerdiagnose

Zielgruppe

Das Seminar richtet sich an technische Redakteure, Entwickler, Architekten, DevOps-Fachkräfte und Dokumentationsverantwortliche. Besonders geeignet ist es für Docs-as-Code-Projekte, Softwarehandbücher, Architekturentscheidungen, Betriebshandbücher und interne Wissensplattformen.

Voraussetzungen

Erforderlich sind Grundkenntnisse in mindestens einem textbasierten Dokumentationsformat und in Versionsverwaltung. Erfahrungen mit AsciiDoc, Markdown, GitLab oder Sphinx sind hilfreich; die Übungen können auf einen Schwerpunkt angepasst werden. Kroki-Grundlagen werden kompakt wiederholt.

Lernstrecke Schritt für Schritt

1. Schritt 1: Dokumentationsquellen und Ausgaben strukturieren. Text, Diagrammquellen, generierte Bilder und Build-Artefakte erhalten getrennte Verzeichnisse. Namensregeln verhindern Mehrdeutigkeiten und unnötige Binärdateien im Repository.
2. Schritt 2: Kroki-Endpunkte und Betriebsvarianten festlegen. Öffentlicher, interner und lokaler Endpunkt werden funktional abgegrenzt. Konfigurationen bleiben austauschbar, damit Dokumentationsquellen nicht auf eine einzelne Umgebung festgelegt werden.
3. Schritt 3: AsciiDoc-Diagrammblöcke einbinden. Diagrammtyp, Quelle, Attribute, Beschriftung und Ausgabe werden in AsciiDoc beschrieben. Eingebettete und ausgelagerte Quellen werden hinsichtlich Wiederverwendung und Review verglichen.
4. Schritt 4: Lokale AsciiDoc-Vorschau prüfen. Eine unterstützende Editor- oder IDE-Vorschau wird konfiguriert. Abweichungen zwischen lokaler Darstellung und automatisiertem Build werden erkannt und dokumentiert.
5. Schritt 5: Markdown-Workflows aufbauen. Kroki-fähige Erweiterungen oder vorgerenderte Artefakte werden in einen klaren Ablauf eingebunden. Relative Pfade und alternative Textbeschreibungen bleiben über Verzeichniswechsel hinweg stabil.
6. Schritt 6: GitLab-Rendering konfigurieren. Kroki-Endpunkt und erlaubte Diagrammtypen werden für die Plattform festgelegt. Markdown-, AsciiDoc- und weitere unterstützte Textformate werden mit einem kleinen Repository getestet.
7. Schritt 7: Sphinx-Dokumentation erweitern. Diagrammquellen werden in reStructuredText oder Markdown-basierten Sphinx-Projekten verarbeitet. Build-Konfiguration, Abhängigkeiten und Ausgabeziele werden reproduzierbar festgehalten.
8. Schritt 8: Ausgabeformate passend wählen. SVG, Rasterformate und PDF werden für Web, Druck und Archivierung bewertet. Größe, Skalierung, Schrift und Transparenz werden in der Zielumgebung geprüft.
9. Schritt 9: Offline- und Self-Hosting-Szenarien umsetzen. Ein interner Kroki-Endpunkt ersetzt externe Abhängigkeiten. Fallback, Zeitüberschreitung und klare Fehlermeldungen verhindern unbemerkte Lücken im Dokumentationsbuild.
10. Schritt 10: CI-Rendering und Qualitätsprüfungen einrichten. Die Pipeline rendert geänderte Quellen, prüft fehlende Ausgaben und verwaltet Artefakte. Diagrammfehler führen zu einer nachvollziehbaren Build-Meldung.
11. Schritt 11: Versionsbezug und Freigabe sichern. Diagrammquelle, Dokumentationsstand und Softwareversion werden miteinander verknüpft. Freigaben verhindern, dass veraltete Bilder trotz geänderter Quellen veröffentlicht werden.
12. Schritt 12: Integrationsfehler systematisch diagnostizieren. Fehler in Blocksyntax, Dateipfad, Endpunkt, Zertifikat, Diagrammsprache und Build-Umgebung werden über einen festen Prüfpfad voneinander getrennt.

Praxisaufgaben

• Eine Dokumentationsseite mit ausgelagerter Diagrammquelle und lokaler Vorschau erstellen.
• Dasselbe Diagramm in einem zweiten Dokumentationssystem wiederverwenden.
• Einen internen Kroki-Endpunkt konfigurierbar machen, ohne Quellen zu ändern.
• Einen CI-Build mit Diagrammprüfung und Artefaktablage aufbauen.
• Einen absichtlich fehlerhaften Pfad und eine Syntaxstörung anhand der Diagnosekette beheben.

Kompetenzziele

• Kroki in AsciiDoc-, Markdown-, GitLab- und Sphinx-Prozesse integrieren.
• Dokumentationsquellen, generierte Ausgaben und Build-Artefakte sauber trennen.
• Lokale Vorschau und automatisierten Build konsistent konfigurieren.
• Self-Hosting und Offline-Szenarien ohne Quellenabhängigkeit umsetzen.
• Integrationsfehler strukturiert lokalisieren und Dokumentationsfreigaben absichern.