Mermaid / PlantUML - Diagramming Tools

When it comes to explaining a process, I always like to refer to a diagram.
You know the adage, " one picture is worth a thousand words “.

At my previous clients, we were used to diagramming with software like Microsoft Visio, Modelio, etc. They are great tools, easy to use.
Need a box? Just drag and drop it from the toolbox panel.

However, when several people were working on the same project and had to modify the same diagrams, it became cumbersome:

• Detecting changes and doing a diff was complicated
• Updating required the software to be installed
• Templating was not easy or impossible

Then we found a great tool called PlantUML. It solved most of our problems:

• The diagrams were coded, and versioning was easy
• We could store the diagram code with the project sources
• It is free, and there are plugins for many editors (such as Visual Studio Code)
• Diagrams are generated from the code and always rendered the same
• Easy and accessible syntax

Many diagrams types are supported:

• Sequence diagrams
• Usecase diagrams
• Class diagrams
• Object diagram
• Activity diagrams
• Component diagrams
• State diagram
• Timing diagram

For this blog, I’m using Hugo because I wanted to write all my posts in Markdown for more or less the same reasons mentioned above. And it was the same for the diagramming. I wanted something well integrated. Plus, I wanted to test another diagramming tool :-).

And I found Mermaid, which appears to be a well-known tool with a large community.

When I’m writing this article:

• 36k stars on Github
• 3.6k commits
• 250 contributors

I don’t know why it has been out of my radar for so long.

I will use Mermaid for all the diagrams I will write for this blog because:

• The syntax is similar to the PlantUML’s one
• The switch will be smooth
• I can write diagrams directly into my Markdown file, using the <mermaid> tag

{{<mermaid class="text-center">}}
sequenceDiagram
    Bob->>Alice: Hello!
    Alice->>Bob: Good bye!
{{</mermaid>}}

sequenceDiagram
    Bob->>Alice: Hello!
    Alice->>Bob: Good bye!