Make your documentation awesome with PlantUML!

Some time ago, I briefly described one pretty useful Python tool that can draw fantastic diagrams from code: Draw architecture diagrams like a boss! There is yet another tool I can recommend – PlantUML. Despite the initial release in 2009, I have not heard about this tool for a long time. So there is a chance that you also haven’t. If so, do not be put off by the “UML” there. This tool can help in several aspects – from Work Breakdown Structure, Mind Maps, architecture, and deployment, to Sequence or Use Case diagrams.

What is a PlantUML then?

Generally speaking, PlantUML is an open-source tool that uses its own DSL to draw various types of diagrams: Block diagrams, BMPN, C4, Archimate, ERD, Network, Mind Maps, WBS, Gantt charts, visualization of JSON and YAML and UML of course. Pretty impressive collection. The DSL of PlantUML is most of the time pretty understandable so it is easy to draw even complicated diagrams after some practice.

It is possible to generate images from code directly on the website or with help of plugins (among others for IntelliJ, Eclipse, NetBeans, Atom, Notepad++, or even… Word).

Show me your code (or maybe an image?:))

There are lots of useful examples on the PlantUML website. We use PlantUML at work at it already helped a lot with documenting a Sequence Diagram of the app or even understanding the team structure. For obvious reasons, I will only show here a few examples from the PlantUML website, however, it should be enough to give you a taste of this tool.

Deliberately, I am going to completely ignore UML diagrams and focus on other capabilities of this tool.

Mind Maps

Mind Maps can turn even complex concepts into a digestible visual format. Below there is a simple example of a Mind Map written in PlantUML DSL.

@startmindmap
+ OS
++ Ubuntu
+++ Linux Mint
+++ Kubuntu
+++ Lubuntu
+++ KDE Neon
++ LMDE
++ SolydXK
++ SteamOS
++ Raspbian
-- Windows 95
-- Windows 98
-- Windows NT
--- Windows 8
--- Windows 10
@endmindmap

The code above will generate this image:

The good thing is we can use styles to personalize the image. For example:

@startmindmap
<style>
mindmapDiagram {
    node {
        BackgroundColor lightGreen
    }
    :depth(1) {
      BackGroundColor white
    }
}
</style>
* Linux
** NixOS
** Debian
*** Ubuntu
**** Linux Mint
**** Kubuntu
**** Lubuntu
**** KDE Neon
@endmindmap

will produce:

As with every example, there is much more this tool can achieve. Tools like PlantUML are fantastic in terms of versioning the changes as the code can be a subject of a version control system.

Visualization of JSON or YAML

Sometimes files in JSON (or YAML) can get messy. With PlantUML, it is pretty easy to present their structure in a format more acceptable i.e. to a less technical audience. Of course, the output can be further customized to highlight the important data:

@startjson
#highlight "lastName"
#highlight "address" / "city"
#highlight "phoneNumbers" / "0" / "number"
{
  "firstName": "John",
  "lastName": "Smith",
  "isAlive": true,
  "age": 28,
  "address": {
    "streetAddress": "21 2nd Street",
    "city": "New York",
    "state": "NY",
    "postalCode": "10021-3100"
  },
  "phoneNumbers": [
    {
      "type": "home",
      "number": "212 555-1234"
    },
    {
      "type": "office",
      "number": "646 555-4567"
    }
  ],
  "children": [],
  "spouse": null
}
@endjson

will generate:

Work Breakdown Structure (WBS)

Drawing WBS from a very understandable syntax is yet another capability of the PlantUML. WBS structure can be helpful to document anything of a tree structure, i.e. the teams in dept. Of course, WBS can be applied to visualize a granularity of a task, as its name describes.

@startwbs
<style>  
wbsDiagram {  
  .green {  
      BackgroundColor YellowGreen  
  }  
  .blue {  
      BackgroundColor LightSkyBlue  
  }  
}  
</style>
* World
** America <<blue>>
***_ Canada 
***_ Mexico
***_ USA
***_  ...
** Europe <<green>>
***_  Poland
***_  England
***_  Germany
***_  ...
@endwbs

Gantt charts

There are dozens of much better tools for Gantt charts than PlantUML. However, if we want to quickly plot a simple chart within a minute and without dedicated software, PlantUML can be a way to go. Below code:

@startuml
[Prototype design] lasts 5 days
[Prototype implementation] lasts 14 days
[Test prototype] lasts 10 days
[Documentation] lasts 7 days

Project starts 2022-10-01
[Prototype design] starts 2022-10-01
[Prototype implementation] starts at [Prototype design]'s end
[Test prototype] starts at [Prototype implementation]'s end
[Documentation] starts at [Prototype implementation]'s end
@enduml

will generate this simple yet neat chart:

As with all diagrams, the DSL for Gantt charts is much more comprehensive and generated diagrams can become more advanced.

Sequence diagrams

Yet another useful example I want to present is a sequence diagram. Sequence diagrams can help to visualize i.e. the communication between several parties.

@startuml
== Initialization ==

Client -> Server: Authentication Request
Server --> Client: Authentication Response

== Repetition ==

Client -> Server: Another authentication Request
Client <-- Server: another authentication Response
@enduml

With such a simple code, PlantUML can plot a readable sequence diagram:

… and much more!

I have presented just a few examples of what PlantUML can do. It is a pity I was not aware of this tool for a pretty long time – it definitely would help me several times while documenting projects. I was lacking dedicated tools several times and with PlantUML I could generate sequence diagrams, visualize stakeholders and their relations, project timelines, and so on in just a few minutes of writing code. The possibility to store diagrams in Git is an additional benefit. Some diagrams could be also handy in ADRs (How helpful are Architectural Decision Records (ADRs)?).

PlantUML offers much more but I deliberately have not put any further examples – check them out, I am sure you will find them useful!

Last but not least, PlantUML can help you in building your personal knowledge base. Another fantastic tool that can be useful is Obsidian. I have written more about that here: Building your own knowledge database? Try Obsidian.