Der nachfolgende Text wurden mit KI erstellt und kann Fehler enthalten. Fehler gefunden? Bei GitHub editieren
Architekturdiagramme sind weit mehr als nur Pfeile und Kästen. Sie sind zentrale Kommunikationsmittel in der Softwareentwicklung und müssen sorgfältig gestaltet werden. Ralf D. Müller, Chief Architect bei DB Systel, teilt in einem aktuellen Interview seine langjährige Erfahrung mit Architekturdokumentation und gibt praktische Tipps für bessere Diagramme.
Von der Dokumentationskrise zum DocToolChain-Projekt
Müller begann seine Reise als Entwickler und erkannte schnell: Architektur ist Kommunikation. Die traditionelle Dokumentation mit Textverarbeitungsprogrammen erwies sich als unpraktisch – Diagramme mussten manuell aktualisiert werden, Versionen stimmten nicht überein, und die Wartung wurde zum Albtraum. Die Lösung: automatisierte Diagrammexporte mittels Scripts, die später zum Open-Source-Projekt DocToolChain führten.
Das Kernprinzip: Dokumentation als Code. Mit dieser Methode lassen sich Diagramme aus UML-Tools automatisiert exportieren und in die Dokumentation einbinden. Besonders praktisch: Wird das Modell aktualisiert, aktualisieren sich die Diagramme automatisch mit.
Die richtige Wahl der Diagrammwerkzeuge
Heute stehen mehrere Optionen zur Verfügung:
- PlantUML: Ideal für Sequenzdiagramme und textbasierte Ansätze mit Git-Integration
- Draw.io/diagrams.net: WYSIWYG-Editor mit PNG/SVG-Export, bei dem die Quellen direkt im Format gespeichert sind
- Mermaid: JavaScript-basiert, modern und flexibel
Der Vorteil textbasierter Tools wie PlantUML zeigt sich bei der Zusammenarbeit: Unterschiede in der Git-Historie sind sofort erkennbar. Ein oft übersehener Vorteil: Blinde Entwickler können PlantUML-Diagramme beschreiben und bauen, was die Accessibility erheblich verbessert.
Gestaltungsprinzipien für lesbare Diagramme
Die Qualität eines Diagramms hängt nicht nur vom Tool ab. Müller empfiehlt folgende Regeln:
Weniger ist mehr: Die “7±2-Regel” – maximal 7 bis 9 Elemente pro Diagramm – sorgt für Übersichtlichkeit. Das Diagramm sollte ohne Zoomen auf einem Standard-Monitor lesbar sein.
Visuelle Sprache: Farben, Größen und Abstände haben Bedeutung. Grün signalisiert “stabil”, Rot warnt vor Problemen. Konsistente Größen vermeiden Verwirrung. Eine Legende erklärt die verwendeten Symbole, Farben und den Autor.
Hierarchien nutzen: Simon Browns C4-Modell (Context, Container, Components, Code) hilft, die richtige Abstraktionsebene zu finden und komplexe Architekturen verständlich zu machen.
White Space kontrollieren: Enge Abstände zwischen Elementen machen Diagramme lesbarer. Kleine, unleserliche Schriften sind der Feind guter Dokumentation.
Werkzeuge und Automatisierung
DocToolChain hat sich von einem Gradle-Projekt zu einer technik-unabhängigen Lösung entwickelt. Es unterstützt nun Docker, verschiedene Markup-Sprachen und kann Ergebnisse als HTML-Microsite, PDF oder Confluence-Export ausgeben. Besonders praktisch: Die Integration von Diagramm-Tools wie PlantUML und Mermaid über den Kroki-Server sowie die Möglichkeit, Excel-Tabellen in strukturierte Dokumentation zu konvertieren.
Fazit
Gute Architekturdiagramme entstehen durch das Zusammenspiel von richtigem Werkzeug, durchdachtem Design und automatisierter Wartung. Der “Documentation-as-Code”-Ansatz mit Tools wie DocToolChain löst das zentrale Problem: Diagramme bleiben aktuell, ohne dass Developer ihre IDE verlassen müssen. Die Beachtung visueller Prinzipien und Zugänglichkeitsstandards macht Diagramme nicht nur schöner, sondern hilft dem gesamten Team – und gerade blinden Entwicklern – besser zu arbeiten.