Seminar Structurizr Dokumentation und Architecture Decision Records

Diagramme beantworten nicht jede Architekturfrage. Ergänzende Texte und nachvollziehbare Entscheidungen werden deshalb direkt mit dem Workspace verbunden und gemeinsam mit dem Modell versioniert und veröffentlicht.

Inhaltsverzeichnis

1. Einordnung
2. Zielgruppe
3. Voraussetzungen
4. Lernziele
5. Seminarinhalte
6. Praxisfall und Übungsartefakte

Einordnung

Structurizr kann Markdown- oder AsciiDoc-Inhalte sowie Architecture Decision Records zusammen mit Diagrammen, Modell und Metadaten darstellen. Damit entsteht ein zusammenhängender Architekturstand, ohne Diagramme und Entscheidungshistorie in voneinander getrennten Ablagen zu pflegen.

Zielgruppe

Softwarearchitektinnen und Softwarearchitekten, technische Leads, technische Redaktionen, Entwicklerinnen und Entwickler sowie Verantwortliche für Architekturentscheidungen und Dokumentationsstandards.

Voraussetzungen

Grundkenntnisse der Structurizr DSL und grundlegende Erfahrung mit Markdown oder AsciiDoc. Kenntnisse eines ADR-Formats sind hilfreich, aber nicht erforderlich.

Lernziele

• Dokumentationsabschnitte sinnvoll gliedern und dem passenden Modellkontext zuordnen.
• Markdown- oder AsciiDoc-Dateien mit der DSL in den Workspace integrieren.
• Live-Diagramme und Bilder kontrolliert in Dokumentationsabschnitte einbetten.
• ADRs mit konsistentem Status, Datum, Titel und Verweisen verwalten.
• Dokumentation, Entscheidungen und Modell in einen gemeinsamen Review-Prozess überführen.

Seminarinhalte

1. Dokumentationsstruktur und Verantwortungsgrenzen

Zunächst wird festgelegt, welche Inhalte als Modell, Diagramm, Dokumentation oder Entscheidung geführt werden.

1. Informationsarten und Zielgruppen erfassen.
2. Abschnittsstruktur und Dateinamenskonvention definieren.
3. Dokumentationsverantwortung auf Workspace-, System- oder Container-Ebene zuordnen.

2. Dokumentation mit Markdown oder AsciiDoc

Die vorbereiteten Dateien werden in eine wartbare Repository-Struktur eingebunden.

1. Dokumentationsverzeichnis neben der DSL anlegen.
2. Inhalte mit der passenden DSL-Direktive importieren.
3. Überschriften, Abschnittsnummerierung und Navigation in Local und Server kontrollieren.

3. Diagramme und Bilder einbetten

Architekturdiagramme werden ohne manuell gepflegte Kopien in den Text integriert.

1. Stabile View-Keys für Einbettungen festlegen.
2. Live-Diagramme im Dokumentationskontext einfügen und Parameter prüfen.
3. Lokale Bilder versionieren und Pfade auf Portabilität kontrollieren.

4. Architecture Decision Records

Entscheidungen werden als leichtgewichtige, chronologische Datensätze aufgebaut.

1. ADR-Vorlage mit Kontext, Entscheidung und Konsequenzen festlegen.
2. Statusübergänge wie vorgeschlagen, akzeptiert und ersetzt konsistent verwenden.
3. ADRs importieren, sortieren und mit Modell sowie Dokumentation verknüpfen.

5. Review und Veröffentlichung

Zum Abschluss wird ein gemeinsamer Qualitätsprozess für Texte, Entscheidungen und Diagramme etabliert.

1. Vollständigkeit, Aktualität und widerspruchsfreie Aussagen prüfen.
2. Änderungen gemeinsam mit dem Workspace versionieren und freigeben.
3. Darstellung in Local und Server anhand einer Abnahmecheckliste kontrollieren.

Praxisfall und Übungsartefakte

Eine vorhandene Architektur wird um mehrere Dokumentationsabschnitte, eingebettete Views und eine kleine ADR-Historie ergänzt. Als Ergebnis liegen eine portable Verzeichnisstruktur und eine Review-Checkliste vor.