Boxes and arrows with Mermaid

Sooner or later when creating software you end up drawing diagrams to understand and to explain how the system you are building works. The best drawings are those you create on a whiteboard while talking. Here you can communicate a ton of information in short time. You can also use online tools such as Witeboard to have conversations about software design in a video call, less efficient but doable.

However, for design documents and system documentation you want diagrams that are a little bit more polished and that can be read by future generations of developers. I find that Mermaid is a great tool for creating and maintaining such diagrams.

This post is a short primer to Mermaid with a some personal insights including why I find Mermaid superior to alternatives such as Visio and Gliffy.

What Mermaid can do for you

Mermaid is a diagramming and charting tool that renders Markdown-inspired text definitions to create and modify diagrams dynamically. Essentially, you write a specification of what diagram you want, then Mermaid creates the diagram for you.

What is super nice is that you have a textual representation of the diagram that you can embed directly in your wiki. Changes to the diagram are visible in the page history just like textual changes. When the system changes later, editors can update the diagram at the same time when they update the system documentation without installing or licensing additional software.

Another very nice feature of Mermaid is that there is a WordPress plugin for it which just underlines how versatile it is. So it is super easy for me to show you some examples. If I want to go back later and fix an error in this post, I just edit the Mermaid markup directly.

Example: Component View

Component views show a static view of how the components of a system relate. Components can be as small as an instance of a single class or they can abstract away something much more complex.

In Mermaid we can create a simple component view using a flowchart diagram. The syntax

flowchart LR
   Consumer --> Provider

generates the following diagram:

While some people read arrows as the direction in which data flows, I find it most useful to have arrows represent dependencies. In the above diagram, the Consumer depends on Provider to fulfil its function in the architecture. Hence, even with such a simple diagram, we need a key or legend to explain what the boxes and arrows mean. Never trust a diagram without a legend.

The flowchart diagram syntax allows you to customise the appearance of arrows and boxes and to put labels on arrows. Here is another example that illustrates some of these features.

flowchart TD
  database[(Database)]
  client[Web client]
  server[Web server]

  client --https--> server

  subgraph .
    server --SQL--> database
  end

Example: Class diagram

I don't often draw class diagrams as these don't communicate much else than what is in the source code. If you need a class diagram, then perhaps your model is too complex. Or maybe it is just me.

Anyway, if you need one, Mermaid has you covered:

classDiagram
  Creature <|-- Mermaid
  Creature <|-- Fish
  Ocean o-- "*" Creature : contains

Example: Sequence Diagram

A much more usable diagram for talking about how a software system works is the sequence diagrams (also known as swim lanes). Sequence diagrams show how different actors or components talk to one another in an example flow.

Mapping out a sequence diagram is a great way to expose misunderstandings and false assumptions. Authentication. Protocols. Identifiers. Logging. Message types. Time outs. Error messages. These are all too often implicitly assumed in a component view while essential to implementing the system. While things quickly get too complicated to flesh out more than a few sample sequence diagrams, these first few will be well worth your time.

With Mermaid sequence diagrams you can create these and discuss and update with stakeholders during a requirements session. Here is a simple example.

sequenceDiagram
  participant human as Alice
  participant cat as Cheshire Cat
  human->>cat: Would you tell me, please, which way I ought to go from here?
  activate cat
  cat->>human: That depends a good deal on where you want to get to.
  deactivate cat
  human->> cat: I don't much care where.
  activate cat
  cat->>human: Then it doesn’t matter which way you go.
  deactivate cat

When to use Mermaid

Mermaid doesn't make the most beautiful illustrations. That is a strength! Beautiful diagrams are dangerous! People look at them and tend to think: It looks nice, hence it must be correct. In marketing, this is desirable. In engineering, it is dangerous.

A diagram is simplified drawing of something complex. Just like a map. It does not tell you the whole story. It may not even tell you a correct story. As a reader, you need to put in effort to understand the diagram, what it says, and what it does not tell you. A rough illustration that can be easily updated invites you to engage. If you find a mistake, you can correct it. If your change was incorrect, you can roll it back. The diagram becomes an active part of the documentation, just like the text. Engaging with the diagram is a conversation, not like reading mysterious stone tablets from the past.

If you want to sell a product or service, by all means use Power Point. If you want documentation that only your architects can understand and maintain, by all means use Visio. If you are on Confluence and don't mind paying for training and licensing, Gliffy may be for you. If you are on Azure DevOps and need a maintainable diagrams for your system documentation, go for Mermaid.

Available now

I'm available for new assignments. The role I'm looking for may be called Technical Project Manager, Tech Lead, Full Stack Developer, or System Architect. I'm looking for a permanent position in the Stockholm area in a product delivery organisation. Get in touch if you need a hands on problem solver with 20 years of experience within software development.