Learning to Love Sequence Diagrams Thanks to Mermaid

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

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 blog post on Mermaid 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 incredibly quick to update, 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, and play with the examples of other types of diagrams.

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