Skip to content
Darren Hickling

Learning to Love Sequence Diagrams Thanks to Mermaid

Creating even simple sequence diagrams drove me to distraction, but the code-driven approach from Mermaid has finally solved that problem.

Published on 2 min read

A sequence diagram of me asking another tool, then Mermaid, to draw and redraw a sequence diagram; only Mermaid manages the change in one line
Authors

One of the biggest challenges I have faced since becoming a Technical Architect is consistently conveying my ideas with diagrams. I keep a Sharpie (opens in a new tab) by my side and preferred quick (terrible) sketches to immediately reaching for tools such as diagrams.net (opens in a new tab).

Gradually, I started collaboratively creating diagrams during video calls, and thanks to my awesome colleagues, have expanded my repertoire of diagramming techniques to convey my intended designs and approaches. One diagram type still frustrated me, though: sequence diagrams. I enjoy the vast degree of control over manually-curated AWS architecture diagrams, but forgetting an important chain of events in a sequence diagram often meant a frustratingly-slow process of rebuilding the entire diagram. Repeating this process one too many times has left me conflating architecture and data flow diagrams, often confusing their purpose.

I remember reading the GitHub (opens in a new tab) blog post on Mermaid (opens in a new tab) support, but only recently did a colleague remind me of it, as I was grappling with a problem that really needed explanation with sequence diagrams. I had also taken to writing down the steps sequentially, which were dropped and adapted into a Mermaid code block.

A few diagrams later and I am fully converted: the diagrams look great, are quick to update with a one-line change, and I have not needed total pixel-level control. If you're interested, here is the code that produced the banner image for this blog post 😄

sequenceDiagram
    autonumber
    actor Darren
    Darren->>+Other Tool: Can you help me draw a sequence diagram?
    Other Tool-->>Darren: Hi Darren, absolutely!
    Darren->>Other Tool: Why is changing a sequence so painful?
    Other Tool-->>-Darren: IDK KTHXBYE
    note over Darren, Other Tool: Bangs head on desk, discards the idea of a sequence diagram
    Darren->>+Mermaid: Can you help make sequence diagrams easier to change?
    Mermaid-->>Darren: Absolutely, go ahead!
    Darren->>Mermaid: Here's my one line change, can you redraw please?
    Mermaid-->>-Darren: No problem, hope you like it 😁
    note right of Darren: Does a happy dance, decides to write a blog post

Don't take my word for it: try editing that code in the Live Editor (opens in a new tab), and play with the examples of other types of diagrams.

As much as I continue to enjoy using diagrams.net (opens in a new tab) for architecture diagrams in particular, I am now far keener on the idea of using a code-first approach to generate C4 models (opens in a new tab) and more. Bring on architecture diagram Pull Requests!