Diagrams as Code with PlantUML
Creating diagrams is a necessary part of every good documentation. But which tool do you use to create them? Visio? Signavio? Or just PowerPoint or Paint? In my opinion is clearly doesn't matter that much, as long as everyone using it after you is able to make changes to it, so it stays up-to-date and correct.
In this article I want to show a tool that creates diagrams from text-files, i.e. you describe a diagram sematically rather than draw shapes and imply the semantic.
The tool is called PlantUML. It is OpenSource, written in Java and thus available to all platforms.
So how does it work, what does it offer?
PlantUML offers support for a whole set of diagram types, among them are:
- Sequence diagram
- Usecase diagram
- Class diagram
- Object diagram
- Activity diagram
- Component diagram
- Deployment diagram
- State diagram
- Timing diagram
You can basically use any editor you like, from Sublime, IDEA, Neovim, Emacs, Notepad. I'd recommend to start with Visual Studio Code and the PlantUML extension.
Sequence diagrams help show complex request-response-cycles, or activity diagrams can outline complex algorithms. Or simply create a diagram to show how your infrastructure is set up. Either way, you will need to look into the documentation to know the syntax. Probably the "hardest" part, but as easy as reading an API documentation. 😉
Now let's look at a first activity diagram example.
@startuml demo-graph2 title Writing Markdown skinparam ActivityBackgroundColor #8ae6ae skinparam ActivityBorderColor #74a82a skinparam ArrowColor #3565a1 skinparam DefaultFontName Fira Code start :Read about the format; :Install the editor; :Try some examples; :Start writing; :Check the published output; :Use it daily; if (Do you like it) then (yes) :Perfect; else (no) :Me sad.; endif stop @enduml
As you can see, it almost reads like the pseudo-code you probably had to write at school/university. And that means, even in it's code-state, it stays readable, as long as you have a text editor. 😁
As for the output, it will look like this.
Now the nice part is, if you edit the text file, you'll get it realigned. No messing around with moving boxes any more. Also you can get code-diffs, if something changed. Generally speaking, all the things you love (or hate) about git are present here: code-share, diff, branching, pull-requests .... it all applies to your diagrams now!
But there's more. Imagine you'd like to make a swimlane out of it. In PlantUML you can simply add the "responsible" lane by surrounding it's name with | (pipe).
So here's the sample with swimlanes:
@startuml demo-graph2 title Writing Markdown skinparam ActivityBackgroundColor #8ae6ae skinparam ActivityBorderColor #74a82a skinparam ArrowColor #3565a1 skinparam DefaultFontName Fira Code |left brain| start :Read about the format; |right brain| :Install the editor; |left brain| :Try some examples; |whole brain| :Start writing; :Check the published output; :Use it daily; if (Do you like it) then (yes) :Perfect; else (no) :Me sad.; endif stop @enduml
And your immediate result is this:
So changing a task to a different lane is as easy as moving a line of code up or down. I typically use this for interviews. Starting with a bullet list, then change it to task and later discuss with everyone which lane it belongs to.
That's when you start to model, instead of just drawing boxes. 🎉
If this acticle got you interested, just give it a try. If you want to know more, just reach out to me.
Newest job offers
Logistics Engineer - project implementations
VoIP Operations Engineer
Business Information Security Officer
Senior Cloud Engineer (AWS, GCP, Azure)
Head of Service Operations
Create Your Own Career
On our career website "Create Your Own Career" you can discover the wide range of entry and career opportunities at Bertelsmann and be inspired by our employee stories!Find more interesting jobs