Member-only story
Making Diagrams Fun With Mermaid
Sometimes, a good diagram is the best way to visualize a concept
If you’ve studied software engineering in a traditional way and had some experience in the industry, you might be wondering how I can use “fun” and “diagrams” in the same sentence. Give me a few minutes of your time and you’ll learn how.
Do We Really Need Diagrams?
It is easy to overlook diagrams when you’re working at a non-corporation. Diagrams are often used in corporate companies with many teams, departments, engineers, outsourced resources, and complicated legal obligations.
In such cases, they’re often used as bureaucratic tools rather than as a way to transfer knowledge. This made hundreds of engineers I’ve worked with hate diagrams as a way to document things.
Yet, we still draw diagrams on whiteboards when we’re onboarding new teammates, discussing new architecture ideas, or presenting the roadmaps of our projects.
That’s because, sometimes, it’s nearly impossible to explain things with words.
Below is a flowchart from Slack that presents the app and decides whether to send a notification or not.
Can you imagine documenting this by using only text? Or even worse, can you explain this verbally to someone and hope that they will actually remember it?
Why Don’t We Use More Diagrams Already?
Something I’ve seen often among software engineers is that drawing sequence or state diagrams or even some basic flowcharts are very much dreaded by many people.
Developers often appreciate a well-drawn graph for explaining software or infrastructure architecture but they’re very reluctant to draw one themselves. The most common reason for this is the tooling required to draw a diagram.
There are dozens if not hundreds of diagram-drawing tools out there with essentially similar but practically different interfaces. It takes an effort to learn this new UI, draw what you want to draw…
