Diagramm oder Doku? Warum nicht beides!

In diesem Vortrag geht es um PlantUML, AsciiDoc und Antora als Single-Source-of-Truth für Architektur und Dokumentation

In vielen Softwareprojekten existieren Diagramme und Dokumentationen in verschiedenen Versionen und an unterschiedlichen Orten – oft mit widersprüchlichen Inhalten. Doch was, wenn Architekturdiagramme und Dokumentation direkt aus einer einzigen Quelle generiert werden könnten?

Dieser Vortrag zeigt, wie PlantUML nicht nur Diagramme, sondern auch zusätzliche Informationen in speziell formatierten Kommentaren aufnehmen kann. Diese werden herausgeparsed und in AsciiDoc überführt, um eine vollständige und stets aktuelle Dokumentation zu erzeugen. Mit Antora wird das Ganze modularisiert und als konsistentes Wissensportal bereitgestellt.

Anhand eines erfolgreichen Proof of Concept im Kundenauftrag demonstrieren wir, wie diese Toolchain in der Praxis funktioniert – inklusive Automatisierung durch GitLab CI. Das Ergebnis: weniger Wartungsaufwand, konsistente Dokumentation und immer aktuelle Architekturübersichten.

Vorkenntnisse

Nützlich sind:

• Grundlegendes Verständnis von Softwarearchitektur und -diagrammen
  
• Erfahrung mit technischer Dokumentation
  
• Grundkenntnisse in PlantUML
  
• Grundwissen zu AsciiDoc oder Markdown
  
• Basiswissen zu CI/CD-Pipelines
  
• Erfahrung mit Versionskontrolle (Git)

Lernziele

• Vorteile von “Single-Source-of-Truth”
  
• PlantUML als (zentrale) Dokumentationsquelle nutzen
  
• Einsatz von Asciidoctor für strukturierte, im Team gepflegte Dokumentation
  
• Antora für die Veröffentlichung
  
• Automatisierung (am Beispiel Gitlab CI)
  
• Best Practices für nachhaltige Dokumentation
  

Wer Dokumentation effizient und nachhaltig gestalten möchte, sollte auf einen Single-Source-of-Truth-Ansatz setzen – für weniger Redundanz, weniger Pflegeaufwand und mehr Konsistenz.