When I was in college, one of my software engineering class obsessed over UML diagrams. Creating them was painful, especially with the clunky tools available in the late 00s, and it felt like an exercise in frustration more than anything useful.
So when I entered the real world and discovered that most teams didn’t make diagrams regularly, I was honestly relieved. But over the years, I realized something: diagrams are incredibly valuable, we just never had tools that made them worth the effort.
My last team relied on diagrams for planning, communicating with non-technical stakeholders, and even thinking through refactors. But the visual tools we used were still slow, fiddly, and frustrating. (Looking at you, arrows that refuse to anchor to properly.)
Then someone introduced the team to Mermaid,, and everything changed.
This post gives a quick rundown of what Mermaid is, how we used it, and why you should consider adding it to your engineering toolkit. (Not sponsored — just a fan.)
Why Diagrams Actually Matter
Even if many teams skip diagramming, the benefits are huge:
- Discover architectural gaps early.
- Visual representation of the system helps technical and non-technical teammates understand intention.
- Easily surfaces dependencies.
- Creates referenceable documentation, decreasing the reliance on tribal knowledge
The real issue isn’t that diagrams aren’t useful, it’s that diagramming has historically been slow and miserable. And in my opinion, Mermaid fixes that
Introduction to Mermaid
Per Mermaid:
Mermaid lets you create diagrams and visualizations using text and code.
It is a JavaScript based diagramming and charting tool that renders Markdown-inspired text definitions to create and modify diagrams dynamically.
Sure, they offer a traditional visual editor (and even an AI diagramming tool now), but the real power is in the “diagrams-as-code” approach.
A simple class diagram looks like this:
---
title: "Animal example"
---
classDiagram
note "From Duck till Zebra"
Animal <|-- Duck
note for Duck "can fly\ncan swim\ncan dive\ncan help in debugging"
Animal <|-- Fish
Animal <|-- Zebra
Animal : +int age
Animal : +String gender
Animal: +isMammal()
Animal: +mate()
class Duck{
+String beakColor
+swim()
+quack()
}
class Fish{
-int sizeInFeet
-canEat()
}
class Zebra{
+bool is_wild
+run()
}
and becomes:
The syntax is easy to pick up, expressive enough for complex diagrams, and supported by many tools developers already use like GitHub and Notion.
Where Mermaid Shined for My Team
1. Technical Planning & Architectural Thinking
One of our junior engineers kept rushing into implementation, which led to rework during code reviews. When we gave them a feature track to lead as part of their career development efforts, we also asked them to write a tech spec, including class diagrams and sequence diagrams, ahead of the rest of the team coming onto the track.
They used Mermaid for everything.
The result?
A living, frequently referenced document that evolved along with the project. It clarified dependencies, surfaced edge cases, and gave the whole team shared context.
Mermaid made that possible because diagrams were fast to write and easy to update.
2. Living Documentation (Instead of Stale Images)
Traditional diagrams rot quickly.
With Mermaid, the “source of truth” isn’t a PNG — it’s the code that generates the diagram. Easy to update, diffable, and version-controlled.
We started keeping diagrams within the rest of our Notion documents and RFC PRs. They were updated as the system evolved. For once, diagrams didn’t feel like artifacts from a previous era, they felt alive and you knew how to modify them.
3. Clear Communication With Non-Technical Stakeholders
I was once asked to create diagrams explaining:
- Where data lived
- What systems existed around the monolith and the microservice
- The flow of operations end-to-end
With Mermaid, I quickly built:
- An architecture diagram
- A mind map
- A sequence diagram
These weren’t one-off illustrations, they evolved as discussions progressed. We even used them when onboarding a new PM to show pain points introduced by the microservice.
The feedback was overwhelmingly positive. Mermaid diagrams made complex systems legible.
Closing Thoughts
Mermaid removed all the friction that used to make diagramming feel like a chore. Suddenly diagrams were fast to create, easy to maintain, and actually fun. Our team saw a noticeable adoption spike once engineers realized how powerful and lightweight the tool was.
Developers often rush to implementation or skip documentation because visual tools slow them down. Mermaid flips that dynamic — it makes diagramming feel like writing code: quick, iterative, versionable.
If you’ve avoided diagrams because the tooling was awful… give Mermaid a try. It might change the way you design systems.
Are you already a Mermaid user? Thinking of trying it out? I’d love to hear your experience.
If you want to read more from me, check out my Being A Great Developer Is More Than Just Code Output series:
Top comments (0)