Seminar PlantUML Intensiv – Softwarearchitektur und Dokumentation

Dieses Intensivprogramm fasst die Architektur-, Daten- und Dokumentationsthemen des Portfolios zusammen. C4, ArchiMate, Komponenten, Deployment, Netzwerke, Datenmodelle, formale Spezifikationen und Documentation-as-Code werden zu einer konsistenten technischen Dokumentationslandschaft verbunden.

Inhaltsverzeichnis

• Zielgruppe
• Voraussetzungen
• Lernziele
• Kapitel 1: Architekturfragen, Sichten und Repository
• Kapitel 2: C4 System Context und Container
• Kapitel 3: C4 Komponenten, Dynamik und Deployment
• Kapitel 4: ArchiMate und Enterprise-Sichten
• Kapitel 5: Komponenten, Netzwerke und Sicherheitsgrenzen
• Kapitel 6: Datenmodelle und strukturierte Daten
• Kapitel 7: Formale und ergänzende Diagramme
• Kapitel 8: Documentation-as-Code
• Kapitel 9: Gestaltung, Bibliotheken und Qualität
• Kapitel 10: Capstone: veröffentlichbare Architekturdokumentation
• Durchgängiges Praxisprojekt
• Methodik

Zielgruppe

Enterprise-, Solution- und Software-Architekten, Data Architects, technische Redaktionen, Lead Developers, Plattformteams und Verantwortliche für Architekturkommunikation.

Voraussetzungen

Grundkenntnisse in Software- oder Unternehmensarchitektur sowie Versionsverwaltung. Einfache PlantUML-Syntax sollte gelesen werden können.

Lernziele

• Architektursichten nach Stakeholder, Ebene und Entscheidungsbedarf strukturieren
• C4-, ArchiMate-, Komponenten-, Deployment- und Netzwerksichten konsistent verbinden
• Datenmodelle und technische Spezifikationen in die Architekturdokumentation integrieren
• Markdown- und AsciiDoc-basierte Dokumentation reproduzierbar aufbauen
• ein modularisiertes Architektur-Repository mit Reviews und Veröffentlichungsprozess erstellen

Kapitel 1: Architekturfragen, Sichten und Repository

Das Kapitel verbindet vier aufeinander aufbauende Arbeitsschritte: Stakeholder, Entscheidungen und Informationsbedarf erfassen, Sichttypen und Abstraktionsebenen zuordnen, gemeinsame Begriffe, IDs und Systemgrenzen definieren sowie Repository-Struktur für Modelle und Dokumente entwerfen. Die Inhalte werden an einem nachvollziehbaren Beispiel aufgebaut, unmittelbar gerendert und anhand der fachlichen Aussage bewertet.

1. Schritt 1 – Analysieren: Stakeholder, Entscheidungen und Informationsbedarf erfassen.
2. Schritt 2 – Modellieren: Sichttypen und Abstraktionsebenen zuordnen.
3. Schritt 3 – Erweitern: gemeinsame Begriffe, IDs und Systemgrenzen definieren.
4. Schritt 4 – Prüfen: Repository-Struktur für Modelle und Dokumente entwerfen.

Praxisübung

Für den Schwerpunkt „Architekturfragen, Sichten und Repository“ 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: C4 System Context und Container

Das Kapitel verbindet vier aufeinander aufbauende Arbeitsschritte: Personen, Systeme und externe Abhängigkeiten modellieren, Container und Verantwortungsgrenzen bestimmen, Technologien und Kommunikationswege beschreiben sowie Kontext- und Container-Sicht konsistent halten. Die Inhalte werden an einem nachvollziehbaren Beispiel aufgebaut, unmittelbar gerendert und anhand der fachlichen Aussage bewertet.

1. Schritt 1 – Analysieren: Personen, Systeme und externe Abhängigkeiten modellieren.
2. Schritt 2 – Modellieren: Container und Verantwortungsgrenzen bestimmen.
3. Schritt 3 – Erweitern: Technologien und Kommunikationswege beschreiben.
4. Schritt 4 – Prüfen: Kontext- und Container-Sicht konsistent halten.

Praxisübung

Für den Schwerpunkt „C4 System Context und Container“ 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: C4 Komponenten, Dynamik und Deployment

Das Kapitel verbindet vier aufeinander aufbauende Arbeitsschritte: relevante Komponenten eines Containers detaillieren, dynamische Abläufe für Schlüsselszenarien darstellen, Deployment Nodes und Instanzen ergänzen sowie Detailtiefe und Wartungsaufwand kontrollieren. Die Inhalte werden an einem nachvollziehbaren Beispiel aufgebaut, unmittelbar gerendert und anhand der fachlichen Aussage bewertet.

1. Schritt 1 – Analysieren: relevante Komponenten eines Containers detaillieren.
2. Schritt 2 – Modellieren: dynamische Abläufe für Schlüsselszenarien darstellen.
3. Schritt 3 – Erweitern: Deployment Nodes und Instanzen ergänzen.
4. Schritt 4 – Prüfen: Detailtiefe und Wartungsaufwand kontrollieren.

Praxisübung

Für den Schwerpunkt „C4 Komponenten, Dynamik und Deployment“ 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: ArchiMate und Enterprise-Sichten

Das Kapitel verbindet vier aufeinander aufbauende Arbeitsschritte: Geschäfts-, Anwendungs- und Technologieebene auswählen, Services, Komponenten und Infrastruktur verknüpfen, Motivation und Transformationsbausteine ergänzen sowie Viewpoints für unterschiedliche Stakeholder ableiten. Die Inhalte werden an einem nachvollziehbaren Beispiel aufgebaut, unmittelbar gerendert und anhand der fachlichen Aussage bewertet.

1. Schritt 1 – Analysieren: Geschäfts-, Anwendungs- und Technologieebene auswählen.
2. Schritt 2 – Modellieren: Services, Komponenten und Infrastruktur verknüpfen.
3. Schritt 3 – Erweitern: Motivation und Transformationsbausteine ergänzen.
4. Schritt 4 – Prüfen: Viewpoints für unterschiedliche Stakeholder ableiten.

Praxisübung

Für den Schwerpunkt „ArchiMate und Enterprise-Sichten“ 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: Komponenten, Netzwerke und Sicherheitsgrenzen

Das Kapitel verbindet vier aufeinander aufbauende Arbeitsschritte: Schnittstellen und Abhängigkeiten präzisieren, Netzsegmente, Zonen und Kommunikationspfade darstellen, Vertrauensgrenzen und externe Zugriffe markieren sowie logische und physische Sichten gegeneinander prüfen. Die Inhalte werden an einem nachvollziehbaren Beispiel aufgebaut, unmittelbar gerendert und anhand der fachlichen Aussage bewertet.

1. Schritt 1 – Analysieren: Schnittstellen und Abhängigkeiten präzisieren.
2. Schritt 2 – Modellieren: Netzsegmente, Zonen und Kommunikationspfade darstellen.
3. Schritt 3 – Erweitern: Vertrauensgrenzen und externe Zugriffe markieren.
4. Schritt 4 – Prüfen: logische und physische Sichten gegeneinander prüfen.

Praxisübung

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

Kapitel 6: Datenmodelle und strukturierte Daten

Das Kapitel verbindet vier aufeinander aufbauende Arbeitsschritte: fachliche Entitäten und Beziehungen modellieren, Kardinalitäten, Schlüssel und relationale Struktur ergänzen, JSON- und YAML-Beispiele visualisieren sowie Datenbegriffe über Architektur- und Schnittstellensichten synchronisieren. Die Inhalte werden an einem nachvollziehbaren Beispiel aufgebaut, unmittelbar gerendert und anhand der fachlichen Aussage bewertet.

1. Schritt 1 – Analysieren: fachliche Entitäten und Beziehungen modellieren.
2. Schritt 2 – Modellieren: Kardinalitäten, Schlüssel und relationale Struktur ergänzen.
3. Schritt 3 – Erweitern: JSON- und YAML-Beispiele visualisieren.
4. Schritt 4 – Prüfen: Datenbegriffe über Architektur- und Schnittstellensichten synchronisieren.

Praxisübung

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

Kapitel 7: Formale und ergänzende Diagramme

Das Kapitel verbindet vier aufeinander aufbauende Arbeitsschritte: EBNF- oder Regex-Spezifikationen visualisieren, Gantt, WBS oder Mindmap passend zur Dokumentationsfrage einsetzen, Salt- oder Ditaa-Skizzen für frühe Entwürfe nutzen sowie Nicht-UML-Sichten klar von Architekturmodellen abgrenzen. Die Inhalte werden an einem nachvollziehbaren Beispiel aufgebaut, unmittelbar gerendert und anhand der fachlichen Aussage bewertet.

1. Schritt 1 – Analysieren: EBNF- oder Regex-Spezifikationen visualisieren.
2. Schritt 2 – Modellieren: Gantt, WBS oder Mindmap passend zur Dokumentationsfrage einsetzen.
3. Schritt 3 – Erweitern: Salt- oder Ditaa-Skizzen für frühe Entwürfe nutzen.
4. Schritt 4 – Prüfen: Nicht-UML-Sichten klar von Architekturmodellen abgrenzen.

Praxisübung

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

Kapitel 8: Documentation-as-Code

Das Kapitel verbindet vier aufeinander aufbauende Arbeitsschritte: Markdown- und AsciiDoc-Module strukturieren, Diagrammquellen, Includes und Medien organisieren, Querverweise, Varianten und Ausgabeformate verwalten sowie lokalen und automatisierten Build angleichen. Die Inhalte werden an einem nachvollziehbaren Beispiel aufgebaut, unmittelbar gerendert und anhand der fachlichen Aussage bewertet.

1. Schritt 1 – Analysieren: Markdown- und AsciiDoc-Module strukturieren.
2. Schritt 2 – Modellieren: Diagrammquellen, Includes und Medien organisieren.
3. Schritt 3 – Erweitern: Querverweise, Varianten und Ausgabeformate verwalten.
4. Schritt 4 – Prüfen: lokalen und automatisierten Build angleichen.

Praxisübung

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

Kapitel 9: Gestaltung, Bibliotheken und Qualität

Das Kapitel verbindet vier aufeinander aufbauende Arbeitsschritte: Themes, Styles und Legenden zentralisieren, C4-, ArchiMate- und eigene Makros versioniert verwalten, Konsistenz- und Qualitätsprüfungen definieren sowie Architektur- und Dokumentationsreviews systematisieren. Die Inhalte werden an einem nachvollziehbaren Beispiel aufgebaut, unmittelbar gerendert und anhand der fachlichen Aussage bewertet.

1. Schritt 1 – Analysieren: Themes, Styles und Legenden zentralisieren.
2. Schritt 2 – Modellieren: C4-, ArchiMate- und eigene Makros versioniert verwalten.
3. Schritt 3 – Erweitern: Konsistenz- und Qualitätsprüfungen definieren.
4. Schritt 4 – Prüfen: Architektur- und Dokumentationsreviews systematisieren.

Praxisübung

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

Kapitel 10: Capstone: veröffentlichbare Architekturdokumentation

Das Kapitel verbindet vier aufeinander aufbauende Arbeitsschritte: relevante Sichten aus dem Gesamtmodell auswählen, Diagramme und erklärenden Text zu einer Publikation verbinden, Build, Links, Begriffe und Lesbarkeit prüfen sowie Dokumentationspaket für Freigabe und Pflege vorbereiten. Die Inhalte werden an einem nachvollziehbaren Beispiel aufgebaut, unmittelbar gerendert und anhand der fachlichen Aussage bewertet.

1. Schritt 1 – Analysieren: relevante Sichten aus dem Gesamtmodell auswählen.
2. Schritt 2 – Modellieren: Diagramme und erklärenden Text zu einer Publikation verbinden.
3. Schritt 3 – Erweitern: Build, Links, Begriffe und Lesbarkeit prüfen.
4. Schritt 4 – Prüfen: Dokumentationspaket für Freigabe und Pflege vorbereiten.

Praxisübung

Für den Schwerpunkt „Capstone: veröffentlichbare Architekturdokumentation“ 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

Für eine beispielhafte digitale Plattform entsteht ein Architektur-Repository mit C4- und ArchiMate-Sichten, technischen Deployment- und Netzwerkdiagrammen, Datenmodell, formaler Spezifikation sowie einer modularen Markdown- und AsciiDoc-Dokumentation.

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.