Seminar PlantUML Documentation-as-Code mit Markdown und AsciiDoc

Diagramme entfalten ihren Wert, wenn Quelltext, Fließtext, Beispiele und Veröffentlichungsprozess gemeinsam versioniert werden. Das Seminar entwickelt einen Documentation-as-Code-Workflow mit Markdown und AsciiDoc, klaren Verzeichnisstrukturen, wiederholbaren Builds und wartbaren Referenzen.

Inhaltsverzeichnis

• Zielgruppe
• Voraussetzungen
• Lernziele
• Kapitel 1: Repository- und Dokumentstruktur
• Kapitel 2: Einbettung in Markdown
• Kapitel 3: Einbettung in AsciiDoc
• Kapitel 4: Build, Varianten und Wiederverwendung
• Kapitel 5: Review und Veröffentlichung
• Durchgängiges Praxisprojekt
• Methodik

Zielgruppe

Technische Redaktionen, Softwareentwickelnde, Architekten, Developer Advocates, Plattformteams und Dokumentationsverantwortliche in produktnahen Teams.

Voraussetzungen

Grundlagen der Versionsverwaltung und einfacher Markdown- oder AsciiDoc-Syntax. PlantUML-Grundlagen sind hilfreich; vorbereitete Diagrammquellen stehen bereit.

Lernziele

• PlantUML-Diagramme sinnvoll in Markdown- und AsciiDoc-Dokumente einbetten
• Quellen, Includes, Medien und Ausgabeformate konsistent organisieren
• lokale Vorschau und automatisierten Dokumentations-Build angleichen
• Querverweise, Diagrammversionen und Wiederverwendung wartbar gestalten
• Review-, Freigabe- und Veröffentlichungsprozesse für Dokumentation etablieren

Kapitel 1: Repository- und Dokumentstruktur

Das Kapitel verbindet vier aufeinander aufbauende Arbeitsschritte: Zielgruppen, Dokumentarten und Ausgabeziele bestimmen, Text-, Diagramm- und Medienquellen trennen, Dateinamen, relative Pfade und Modulgrenzen festlegen sowie eine nachvollziehbare Navigationsstruktur aufbauen. Die Inhalte werden an einem nachvollziehbaren Beispiel aufgebaut, unmittelbar gerendert und anhand der fachlichen Aussage bewertet.

1. Schritt 1 – Analysieren: Zielgruppen, Dokumentarten und Ausgabeziele bestimmen.
2. Schritt 2 – Modellieren: Text-, Diagramm- und Medienquellen trennen.
3. Schritt 3 – Erweitern: Dateinamen, relative Pfade und Modulgrenzen festlegen.
4. Schritt 4 – Prüfen: eine nachvollziehbare Navigationsstruktur aufbauen.

Praxisübung

Für den Schwerpunkt „Repository- und Dokumentstruktur“ entsteht ein eigenständiges Teilmodell. Anschließend werden Syntax, Semantik, Lesbarkeit und Anschlussfähigkeit an das Gesamtprojekt mit einer kompakten Prüfliste kontrolliert.

Kapitel 2: Einbettung in Markdown

Das Kapitel verbindet vier aufeinander aufbauende Arbeitsschritte: Diagrammquellen und gerenderte Bilder passend referenzieren, Editorvorschau und Build-Ergebnis vergleichen, Alt-Texte, Bildunterschriften und Größenangaben ergänzen sowie relative Links und Pfade für verschiedene Ausgabekanäle prüfen. Die Inhalte werden an einem nachvollziehbaren Beispiel aufgebaut, unmittelbar gerendert und anhand der fachlichen Aussage bewertet.

1. Schritt 1 – Analysieren: Diagrammquellen und gerenderte Bilder passend referenzieren.
2. Schritt 2 – Modellieren: Editorvorschau und Build-Ergebnis vergleichen.
3. Schritt 3 – Erweitern: Alt-Texte, Bildunterschriften und Größenangaben ergänzen.
4. Schritt 4 – Prüfen: relative Links und Pfade für verschiedene Ausgabekanäle prüfen.

Praxisübung

Für den Schwerpunkt „Einbettung in Markdown“ entsteht ein eigenständiges Teilmodell. Anschließend werden Syntax, Semantik, Lesbarkeit und Anschlussfähigkeit an das Gesamtprojekt mit einer kompakten Prüfliste kontrolliert.

Kapitel 3: Einbettung in AsciiDoc

Das Kapitel verbindet vier aufeinander aufbauende Arbeitsschritte: PlantUML-Blöcke und Include-Mechanismen verwenden, Attribute für Pfade, Formate und Varianten definieren, Querverweise zwischen Kapiteln und Diagrammen herstellen sowie Dokumentmodule zu größeren Publikationen zusammensetzen. Die Inhalte werden an einem nachvollziehbaren Beispiel aufgebaut, unmittelbar gerendert und anhand der fachlichen Aussage bewertet.

1. Schritt 1 – Analysieren: PlantUML-Blöcke und Include-Mechanismen verwenden.
2. Schritt 2 – Modellieren: Attribute für Pfade, Formate und Varianten definieren.
3. Schritt 3 – Erweitern: Querverweise zwischen Kapiteln und Diagrammen herstellen.
4. Schritt 4 – Prüfen: Dokumentmodule zu größeren Publikationen zusammensetzen.

Praxisübung

Für den Schwerpunkt „Einbettung in AsciiDoc“ entsteht ein eigenständiges Teilmodell. Anschließend werden Syntax, Semantik, Lesbarkeit und Anschlussfähigkeit an das Gesamtprojekt mit einer kompakten Prüfliste kontrolliert.

Kapitel 4: Build, Varianten und Wiederverwendung

Das Kapitel verbindet vier aufeinander aufbauende Arbeitsschritte: lokalen und automatisierten Renderprozess vereinheitlichen, Ausgabeformate für Web, PDF und Präsentation unterscheiden, gemeinsame Diagrammdefinitionen zentral einbinden sowie Varianten nach Produkt, Version oder Zielgruppe erzeugen. Die Inhalte werden an einem nachvollziehbaren Beispiel aufgebaut, unmittelbar gerendert und anhand der fachlichen Aussage bewertet.

1. Schritt 1 – Analysieren: lokalen und automatisierten Renderprozess vereinheitlichen.
2. Schritt 2 – Modellieren: Ausgabeformate für Web, PDF und Präsentation unterscheiden.
3. Schritt 3 – Erweitern: gemeinsame Diagrammdefinitionen zentral einbinden.
4. Schritt 4 – Prüfen: Varianten nach Produkt, Version oder Zielgruppe erzeugen.

Praxisübung

Für den Schwerpunkt „Build, Varianten und Wiederverwendung“ entsteht ein eigenständiges Teilmodell. Anschließend werden Syntax, Semantik, Lesbarkeit und Anschlussfähigkeit an das Gesamtprojekt mit einer kompakten Prüfliste kontrolliert.

Kapitel 5: Review und Veröffentlichung

Das Kapitel verbindet vier aufeinander aufbauende Arbeitsschritte: Text- und Diagrammänderungen gemeinsam reviewen, veraltete oder nicht referenzierte Artefakte erkennen, Freigaberegeln und Versionskennzeichnung definieren sowie Dokumentationspaket reproduzierbar veröffentlichen. Die Inhalte werden an einem nachvollziehbaren Beispiel aufgebaut, unmittelbar gerendert und anhand der fachlichen Aussage bewertet.

1. Schritt 1 – Analysieren: Text- und Diagrammänderungen gemeinsam reviewen.
2. Schritt 2 – Modellieren: veraltete oder nicht referenzierte Artefakte erkennen.
3. Schritt 3 – Erweitern: Freigaberegeln und Versionskennzeichnung definieren.
4. Schritt 4 – Prüfen: Dokumentationspaket reproduzierbar veröffentlichen.

Praxisübung

Für den Schwerpunkt „Review und Veröffentlichung“ entsteht ein eigenständiges Teilmodell. Anschließend werden Syntax, Semantik, Lesbarkeit und Anschlussfähigkeit an das Gesamtprojekt mit einer kompakten Prüfliste kontrolliert.

Durchgängiges Praxisprojekt

Eine kleine Produktdokumentation wird aus modularen Markdown- und AsciiDoc-Quellen aufgebaut. Mehrere PlantUML-Diagramme werden wiederverwendet, lokal gerendert und in einem automatisierten Publikationslauf erzeugt.

Methodik

Fachimpulse, Live-Coding, kommentierte Demonstrationen und schrittweise Übungen wechseln sich ab. Jede neue Technik wird zunächst an einem Minimalbeispiel geprüft, danach in das Gesamtprojekt übernommen und abschließend in einem strukturierten Review bewertet. Alle Übungen verwenden versionierbare Textquellen und reproduzierbare Render-Schritte.