Im Gespräch mit Tobias Ahlers zu Diagrams-as-Code

Tobias wird beim Architektur-Punsch am 15.12.2022 mit seinem Vortrag ‘Build Your Bild – eine “Diagrams as Code”-Fotosafari’ dabei sein. Ich habe ihn im September beim Java Forum Nord in Hannover getoffen. Im folgenden Gespräch gibt er uns einige Einblicke in diese Thematik.

(Falk) “Hallo Tobias, schön dass Du im Dezember dabei sein wirst. Stell Dich bitte kurz vor."

Tobias: “Ich arbeite als Senior Developer bei der smartsteuer GmbH und bin vor allem im Bereich der Java-Entwicklung und der technischen Kommunikation aktiv. Meine Leidenschaft gilt außerdem der Software-Craftsmanship-Bewegung und dem Wissensaustausch in diversen Communitys in und um Ostwestfalen.”

“In Deinem Vortrag verwendest Du die Metapher des Diagramm Dschungels und stellst PlantUML als eine interessante Alternative zur Erstellung von Diagrammen vor. Ist das für Dich die ultimative Vorgehensweise?"

Tobias: Für mich hat dieser Weg viele Vorteile. Ich bin nicht so gut im Malen bzw. Designen von Grafiken. Außerdem spricht mich die Analogie “as-Code” an, also die aus einem Textformat entstandene fertige Grafik analog zum aus dem Sourcecode entstandenen ausführbaren Programm. Zudem kann ich Diagramme so ohne Kontextwechsel einfach in meiner gewohnten Umgebung, der IDE, erstellen. Somit brauche ich meine Komfortzone quasi nicht zu verlassen.

“Das klingt richtig gut. Aber gibt es auch Nachteile?"

Tobias: Nicht-Entwickler werden sich mit diesem Ansatz schwer tun. Sie greifen eher zu graphischen Editoren. Die Entwicklerwerkzeuge wie Versionsverwaltung, Texteditoren und Kommandozeilen-Tools stellen eine gewisse Einstiegshürde dar. Sie sind zudem nicht mit den Abläufen und Prozessen in der Softwareentwicklung vertraut.

Und insgesamt hat man beim Diagrams-as-Code-Ansatz auch nicht die komplette Gestaltungsfreiheit, das Ergebnis wird automatisch erzeugt und das Layout entspricht nicht immer den Erwartungen.

“Für welche Anwendungsfälle eignen sich Diagramme mit Code aus Deiner Sicht am besten?"

Tobias: Ich nutze sie zum Beispiel, um Datenstrukturen wie JSON oder YAML zu visualisieren, also um ein besseres Verständnis dazu aufzubauen. Und wenn ich externe API-Schnittstellen anbinden muss, helfen mir Sequenzdiagramme. Sie lassen mich die Workflows inklusive potentieller Callbacks einfacher verstehen. Außerdem nutze ich gern C4, insbesondere die Komponentendiagramme. Das passt von der Syntax her sehr gut, lässt sich leicht verarbeiten und sieht auch noch ansprechend aus.

Letztlich versuche ich die gesamte Dokumentation leichtgewichtig als Docs-as-Code zu erstellen und bette dann eben auch die Grafiken, z. B. in AsciiDoc, ein. Aber auch Wikis wie Confluence bieten heutzutage den Umgang mit Grafiken aus Textformaten an.

“Wann nutzt Du Alternativen und welche sind das?"

Tobias: Bei großen Diagrammen, z. B. komplexen Komponentendiagrammen, kommt PlantUML an seine Grenzen. Früher habe ich alternativ kommerzielle Grafikeditoren wie Visio eingesetzt. Heute verwende ich eher draw.io (diagrams.net), zum Beispiel auch für Screenshots. Und bei klassischen Architekturdiagrammen ergänzt es sich gut mit den Nachteilen von PlantUML. Man kann zum Beispiel bei einem PNG oder JPG den Inhalt eines Diagramms in den Metadaten ablegen und so die Binärformate jederzeit wieder verlustfrei editieren.

“Sehr interessant. Aber noch mal allgemeiner gefragt, in welchen Projektphasen erstellst Du Architekturdiagramme?

Tobias: Eigentlich schon sehr früh im Entwicklungsprozess, um Datenstrukturen zu verstehen oder Abläufe in Sequenzdiagrammen sichtbar zu machen. Häufig nutze ich es aber auch zum Nachdokumentieren von Bestandssoftware. Auch hier geht es mir um das Verstehen der Legacy Systeme und da hilft es, die Strukturen zu visualisieren.

“Und wie bindest Du Diagramme in Deine Dokumentation ein?"

Tobias: Im Idealfall durch Referenzieren aus leichtgewichtigen Textformaten, wie AsciiDoc. Daraus lassen sich dann PDFs oder auch einfache HTML-Seiten erzeugen. Das Werkzeug docToolchain kann zudem die gesamte Dokumentation auch nach Confluence exportieren und da schließt sich dann der Kreis zu den Nicht-Entwicklern. Die erhalten so zumindestens lesend Zugriff auf Diagrams-as-Code Inhalte.

“Das macht Lust auf mehr. Vielen Dank, dass Du Dir die Zeit für das Interview genommen hast. Ich freue mich schon auf Deinen Vortrag bei unserer Konferenz."

Noch mehr Anregungen erhaltet Ihr am 15. Dezember 2022 bei unserem Architektur-Punsch. Einfach anmelden! Neben dem Vortrag von Tobias gibt es dort viele weitere spannende Programmpunkte zu entdecken.

Save the date…

Architektur-Punsch 2022