Praktischer Tipp: Textuelle Anforderungen mit PlantUML

In vielen Teams wird noch nicht modelliert, sondern textuell spezifiziert. Das erlebe ich immer noch häufig, auch im Umfeld von sehr technischen Anforderungen. Zum Beispiel sehe ich immer noch häufig, wie bei eingebetteten Systemen Zustandsmaschinen in Text beschrieben werden. Das sind Situationen, in denen ein Bild mehr als 1000 Worte sagen kann. Doch die IT bzw. Teamleitung spielt nicht immer mit. Im Folgenden ein Tipp, wie das quelloffene Werkzeug PlantUML hier helfen kann.

Was ist PlantUML?

PlantUML ist ein Werkzeug für die Erstellung von UML-Diagrammen. Dabei wandelt es eine textuelle Repräsentation des Modells in ein Bild um. Damit fällt es eher in die Kategorie der „Malwerkzeuge“. Malen ist im Prinzip ja nicht schlimm, solange wir es nicht mit Modellieren verwechseln. Insbesondere unterstützt ein Bild die Kommunikation (Level 1 des SYSMOD Intensity-Models).

Das besondere an PlantUML ist, dass die textuelle Notation recht leicht vom Menschen zu lesen ist — das ist Absicht. Weiterhin ist PlantUML quelloffen und kann sowohl lokal als auch auf einem lokalen Server installiert werden. Dies ist wichtig für das Verarbeiten von vertraulichen Daten.

Wir können PlantUML aber auch online in einer Webanwendung nutzen. Nicht nur das: PlantUML kann ein Diagramm in einer URL kodieren. Damit können wir Nutzern einen Link zu einem editierbaren Diagramm zur Verfügung stellen.

Ein Beispiel

Ein Bild Beispiel sagt mehr als 1000 Worte. Zunächst ein einfaches Modell mit drei Zuständen einer Tür, die offen, geschlossen und abgeschlossen sein kann. Die Zustände könnten wir textuell beschreiben. Dabei sollte bspw. klar sein, dass die Tür nur abgeschlossen werden kann, wenn sie geschlossen ist. In der PlantUML-Notation sieht das folgendermaßen aus:

[*] -> offen
offen -> geschlossen
offen <- geschlossen
geschlossen -> abgeschlossen
geschlossen <- abgeschlossen

Jede Zeile beschreibt eine Transition. Daraus erkennen wir, dass eine offene Tür erst geschlossen werden muss, bevor sie abgeschlossen werden kann. Die erste Zeile definiert lediglich den Startpunkt und könnte auch weggelassen werden.

Wenn wir diesen Text an PlantUML füttern, bekommen wir das folgende Diagramm:

Wie bereits erwähnt können wir einen Link erzeugen, mit dem dieses Diagramm direkt editiert werden kann. Hier ist der Link (bitte gleich ausprobieren!):

https://www.plantuml.com/plantuml/uml/YzQALT2rKyXFIqlDumAJ86vwQd5oHav-SJ5Sq4ONHH3EXgXFJC8g2TQ7AWa0

Der kryptische Teil nach „…/uml/ ist die kodierte Darstellung des obigen Textes. Noch ein kleiner Hinweis: PlantUML schließt die Diagrammbeschreibung in @startuml und @enduml. Diese Marker können wir natürlich beibehalten, da sie beim automatischen Verarbeiten hilfreich sein können.

PlantUML unterstützt nicht nur Zustandsdiagramme, sondern fast alle Diagrammtypen der UML, sowie andere nützliche Diagrammtypen.

PlantUML Diagrammtypen

PlantUML und Textuelle Anforderungen

Interessant wir es in Teams, die textuell Anforderungen wie diese bearbeiten müssen. Zwar haben viele Anfordungsmanagementwerkzeuge die Möglichkeit, Bilder, oder sogar Diagramme einzubetten. Jama Connect zum Beispiel hat einen eingebauten Editor für Diagramme. Dieser beruht übrigens auf draw.io und kann hier ausprobiert werden. Doch in der Praxis ist diese Lösung unglücklich und in manchen Teams sogar verboten: Eingebaute Bilder sind schnell veraltet. Weiterhin ist ein Vergleich von Versionsständen in der Regel nur visuell möglich. Schlimmer: Nicht-inhaltliche Änderungen (wie bspw. Layoutverbesserungen) triggern ebenfalls Änderungen in der Historie.

In solchen Situationen können wir die textuelle Beschreibung des Zustandsmodells mit dem PlantUML-Text ersetzen. Selbst nichttechnische Mitarbeiter sollten nach einer kurzen Einführung in der Lage sein, die Notation zu lesen. Nicht jeder muss ja das Modell verändern.

Auch das Bild in die Anforderung?

Noch komfortabler wäre es natürlich, zusätzlich zum Text auch das Bild einzufügen. In der Praxis hat sich das bewährt, denn das ist ja schließlich der Grund, die PlantUML-Notation zu nutzen. Wenn dies händisch gemacht wird, muss natürlich doppelt gepflegt werden. Bei jeder Änderung des Textes muss auch das Bild ausgetauscht werden. In der Praxis ist dies nicht wirklich schwer. Der typische Arbeitsfluss sieht folgendermaßen aus:

Ich empfehle, die Notation für das Diagramm nicht über mehrere Anforderungen zu verteilen. Das macht das Bearbeiten zum Albtraum. Außerdem stellt das Zustandsmodell eine zusammenhängende Einheit statt. Falls die Diagramme zu groß werden, sollte der gesamte Ansatz überdacht werden. Vielleicht ist es dann doch Zeit für richtige Modellierung.

Der Versuchung widerstehen

Je nachdem, welches Werkzeug eingesetzt wird und wie flexibel die IT ist, ist natürlich auch Automatisierung möglich. Zum Beispiel könnte bei einer Änderung der Server nach Inhalten suchen, die von @startuml und @enduml umschlossen sind. Für diese könnte der Server dann das Diagramm neu generieren und in ein dafür vorgesehenes Attribut einfügen. In der Praxis würde ich dieses Vorgehen nicht empfehlen: Die Gefahr ist zu groß, dass die Notation Fehler enthält, was die Diagrammgenerierung verhindern würde.

Für manche Nutzer mag auch die Versuchung groß sein, PlantUML im vollen Umfang auszunutzen. Es gibt viele Schalter, um das Layout, das Styling und vieles mehr zu beeinflussen. Doch all dies geht auf Kosten der Lesbarkeit des Textes. Diese Features sind eher für die maschinelle Diagrammgenerierung vorgesehen.

Ebenso schlage ich bei diesem Vorgehen Pragmatismus vor: Sicherlich sollten wir versuchen, möglichst valides UML zu generieren. Doch wir nutzen PlantUML hier in erster Linie für die Kommunikation mit Menschen. Kleine (!) Verletzungen des Standards sind akzeptabel, falls ansonsten die Lesbarkeit des Textes stark sinken würde.

SysML v2 Textnotation

Fazit

Wir sind leider noch weit Mainstream der Modellierung im Systems Engineering entfernt. Dennoch können auch Bilder punktuell einen großen Mehrwert liefern. Der hier vorgestellte Tipp für den Einsatz von PlantUML akzeptiert diese Realität und hilft Teams, dennoch effektiv mit Bildern zu kommunizieren und in einer textbasierten Welt pragmatisch zu versionieren.