Practical tip: Textual requirements with PlantUML

In many teams, textual specifications are still used instead of modeling. I still see this frequently, even in the context of very technical requirements. For example, I still often see embedded systems where state machines are described in text. These are situations in which a picture can say more than 1000 words. But IT or team management doesn't always play along. Here is a tip on how the open source tool PlantUML can help here.

What is PlantUML?

PlantUML is a tool for creating UML diagrams. It converts a textual representation of the model into an image. This puts it more in the category of "painting tools". Painting is not bad in principle, as long as we do not confuse it with modeling. In particular, a picture supports communication (Level 1 of the SYSMOD Intensity Model).

The special thing about PlantUML is that the textual notation is quite easy to read by humans - this is intentional. PlantUML is also open source and can be installed both locally and on a local server. This is important for processing confidential data.

But we can also use PlantUML online in a web application. Not only that: PlantUML can encode a diagram in a URL. This allows us to provide users with a link to an editable diagram.

An example

A Picture Example says more than 1000 words. First, a simple model with three states of a door that can be open, closed and locked. We could describe the states in text form. It should be clear, for example, that the door can only be locked when it is closed. In the PlantUML notation, this looks like this:

[*] -> open
open -> closed
open  closed
closed <- closed

Each line describes a transition. From this we can see that an open door must first be closed before it can be locked. The first line only defines the starting point and could also be omitted.

If we feed this text to PlantUML, we get the following diagram:

As already mentioned, we can create a link with which this diagram can be edited directly. Here is the link (please try it out now!):

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

The cryptic part after ".../uml/ is the coded representation of the above text. Another small note: PlantUML closes the diagram description in @startuml and @enduml. We can of course keep these markers, as they can be helpful for automatic processing.

PlantUML supports not only state diagrams, but almost all diagram types of UML, as well as other useful diagram types.

PlantUML diagram types

PlantUML and textual requirements

It becomes interesting in teams that have to process textual requirements such as these. Many requirements management tools have the option of embedding images or even diagrams. Jama Connect, for example, has a built-in editor for diagrams. Incidentally, this is based on draw.io and can be tried out here. In practice, however, this solution is unfortunate and even prohibited in some teams: Built-in images quickly become outdated. Furthermore, it is usually only possible to compare versions visually. Worse: non-content changes (such as layout improvements) also trigger changes in the history.

In such situations, we can replace the textual description of the state model with the PlantUML text. Even non-technical employees should be able to read the notation after a brief introduction. After all, not everyone has to change the model.

Include the image in the request?

Of course, it would be even more convenient to insert the image in addition to the text. In practice, this has proven to be a good idea, because after all, that is the reason for using the PlantUML notation. If this is done manually, it must of course be maintained twice. Each time the text is changed, the image must also be replaced. In practice, this is not really difficult. The typical workflow looks like this:

I recommend not distributing the notation for the diagram over several requirements. This makes editing a nightmare. In addition, the state model represents a coherent unit. If the diagrams become too large, the whole approach should be reconsidered. Maybe it is time for proper modeling after all.

Resist the temptation

Depending on which tool is used and how flexible the IT is, automation is of course also possible. For example, the server could search for content enclosed by @startuml and @enduml when a change is made. The server could then regenerate the diagram for these and insert it into a designated attribute. In practice, I would not recommend this procedure: The risk is too great that the notation contains errors, which would prevent the diagram generation.

Some users may also be tempted to use PlantUML to its full extent. There are many switches to influence the layout, styling and much more. However, all this comes at the expense of the readability of the text. These features are rather intended for machine diagram generation.

I also suggest pragmatism in this approach: Certainly we should try to generate UML that is as valid as possible. But we use PlantUML here primarily for communication with people. Small (!) violations of the standard are acceptable if the readability of the text would otherwise be greatly reduced.

SysML v2 Text notation

Conclusion

Unfortunately, we are still a long way from the mainstream of modeling in systems engineering. Nevertheless, images can also provide great added value at certain points. The tip presented here for using PlantUML accepts this reality and helps teams to communicate effectively with images and to version pragmatically in a text-based world.