Glorified Plumbing

You may have seen my earlier posts about text-to-diagram tools. Since I was first shown WebSequence Diagram around 2015, I grimace every time I have to use Draw.io, Omnigraffle, or Visio to create a diagram. Websequence Diagram allows you to quickly draw a UML sequence diagram by writing a series of simple statements. You can quickly reorder interactions, add new participants, and add iteration or optional steps. In the WYSIWYG drawing tools, you have to make sure connectors are firmly anchored, avoid dropping an element on a connector (some tools will break the connector in two and attach the moved element to both new connections), and you have to re-bend the connectors to suit your need at times.

Sequence diagrams are not the only diagrams that can be drawn in text. PlantUML supports many diagram types, and the recent upgrades to the PlantText tool have only improved the system. If you have to draw signal waveforms, PlantUML has a fullness to its language but is cumbersome; at that point, WaveDrom becomes the best tool I’ve found.

Last week, I learned about a new tool, Mermaid. It seems this tool has been available for a few short years. I won’t do a full review, but I will give you some teasers. I think this tool is good enough that you need to be aware of it sooner than later. So here is a short blog post for you.

Do I need another diagram tool?

Is my tool kit complete? WebSequence Diagram, PlantText (an editor for PlantUML) and WaveDrom get me about 60% of the way. Adding MindNode to draw mind maps added a new style diagram I had not used before. I must confess I use MineNode to draw my Warnier Orr diagrams; its dendritic nature lends itself well to top-down decomposition. But I still need to go to draw.io periodically.

Sometimes, your diagram gets “too big” for PlantText to distribute everything nicely on its own. Suddenly, the entry point to your state diagram gets placed in the center of the page, and your flow gets rotated around, making it harder to follow, the top of the page having the final states above the early states. Sometimes, PlantText just doesn’t support the diagram you want, as it’s not a UML diagram.

So there’s a newcomer. Mermaid! I had about an hour of playtime with Mermaid last week. I only sought it out after seeing an article about how ChatGPT could take your natural language text, convert it to a state machine description, and then translate that into Mermaid’s internal language so you could render the diagram nicely. You offer that level of automation, and I’m there.

My first attempt with Mermaid via ChatGPT was a simple org chart. My prompt was

Can you give me a sample of mermaid. Lets have a simple org chart example. Frank is the CTO, Jennifer is VP Engineering, charlie is Director of QA. joe, bob and glue are QA testers, charlotte, April and roger are SW engineers.

The response was the usual wordy answer with a code block.

Certainly! Below is a simple example of how you would structure an organization chart using Mermaid syntax to represent the hierarchy you described. In Mermaid, you can use the graph TD syntax to denote a top-down (TD) chart, and then you define the nodes and their connections.

graph TD;
    CTO[Frank - CTO]
    VP_Engineering[Jennifer - VP Engineering]
    Director_QA[Charlie - Director of QA]
    QA_Tester1[Joe - QA Tester]
    QA_Tester2[Bob - QA Tester]
    QA_Tester3[Glue - QA Tester]
    SW_Engineer1[Charlotte - SW Engineer]
    SW_Engineer2[April - SW Engineer]
    SW_Engineer3[Roger - SW Engineer]

    CTO --> VP_Engineering
    VP_Engineering --> Director_QA
    VP_Engineering --> SW_Engineer1
    VP_Engineering --> SW_Engineer2
    VP_Engineering --> SW_Engineer3
    Director_QA --> QA_Tester1
    Director_QA --> QA_Tester2
    Director_QA --> QA_Tester3

Using the on-line editor, the overall experince looked like this

That’s not where the fun ends. I found out that Mermaid is supported within GitHub. You can see in the markdown a Mermaid code block:

And when we hit Preview, you can see that it renders my example wonderfully.

Gone are the days of maintaining a PlantUML markup file, rendering that file as an SVG file, and then linking to the illustration in your .md file. It’s all in one place. Yes, there is a trade-off between adding complexity to your markdown and simplifying your workflow. I know which I’d rather.

As for Draw.io, well, you can use the menu option under arrange->insert->advanced to embed Mermaid (and a couple of other text-to-diagram types) directly into your draw.io file. For all of you using Confluence, you probably just started paying much more attention now.

Until now, I have not had enough time to learn the full details of Mermaid. It’s new to me, and seeing the beta drawing types and the age of their official blog, I think Mermaid is new-ish to the world. I do know that it’s a shiny new toy I want to play with. I hope it will fill the non-UML tool gap.

Will I abandon my trusted toolset? Well, I stopped using WebSequence Diagram about 5 years ago. PlantUML has most of the functionality I want (except concurrent actions in the paid WebSequnce Diagram), but PlantUML is a one-stop shop for other diagram types. I don’t see WaveDrom being replaced by Mermaid any time soon; its use is too obscure and leans more toward hardware rather than software development. As I get familiar with the new syntax, I may find I prefer Mermaid and use it for my state and sequence diagrams.

My immediate need is to use the block diagrams. They are in beta right now, and though I can get them to render in the official Mermaid tool, I do not see them working in GitHub yet. I intend to use this for some upcoming software architecture diagrams. Trust me when I say I am using the simplest format here; you can define how many block columns there are and how many columns can span. I think I need to see if there is a more elegant way to nest block diagrams. For the architecture diagram, I’ll be nesting functionality and APIs within the layers so we know there will be at least one level of nesting.

UPDATE: I got the block-beta diagrams working in GitHub a day after posting this. I don't know what mistake I made, a typo in my code or using GitHub a week too early. That's the trouble with new and evolving tech and not having time to explore every new toy properly.

I just wanted to tell you this technology exists with this teaser.

Tools are always evolving. Some get bloated, some get outpaced. I need the most appropriate tools for my job, so I have to constantly evaluate what is out there, especially to fill my needs. I see Mermaid as an essential tool. As I get familiar with it, I might find it not only fills the current gaps in my toolset but also can replace tools that are harder to use.

There might be other text-to-diagram tools that you like out there. I’d love to hear about them. What do you use them for?