Lately I've become quite a fan of PlantUML, a tool to automatically generate (technical) diagrams from text files. PlantUML takes care of the layout and allows putting your documents into version control like git. I even added support in my blog engine, to properly render and link PlantUML documents in posts (including their source code).

In this post, I'm collecting useful resources that have helped me writing PlantUML documents.

Have the Language Reference Guide always ready

The Language Reference Guide is a quite large PDF file (400+ pages) that contains hundreds of examples on how each feature works. I generally have it open in the background when working with diagrams, as searching in it is much faster than querying the web - as well as using it for inspiration to improve.

The different kinds of participants (screenshot from the reference guide)

VSCode: Use the extension

If you're also using Visual Studio Code as your IDE: There's a useful extension, that adds a near-live preview that greatly improves the workflow (Command Palette -> "PlantUML: Preview current diagram").

Be aware that you need to have a (local) PlantUML server running for this to work. It's generally recommend to either use a local one (e.g. using the Docker image) or host one yourself.

Preview feature of the PlantUML VSCode extension

Add Emoji

Very recently (v1.2021.16, released 08.12.2021) PlantUML added native support for rendering emojis. This can be used to quickly add additional visual context to descriptions without having to import additional icon libraries.

Check out the emoji cheat sheet for additional information and a list of available emojis.

Use the standard library

Apart from the many integrated types of diagrams (like sequences and deployments), newer versions of PlantUML contain a integrated standard library, with content from many third party contributors.

From the standard library, I've mostly used C4, which is "a simple way of describing and communicate software architectures".

Further resources