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.