A few years back, I shifted to remote work due to the pandemic. When I discussed some system workflows with teammates, I always used an online whiteboard to draw diagrams, thinking it would have the same result as the physical one. I was wrong, my mouse skills weren't good enough making it too hard to understand. 🤯
Then, I found Mermaid in a document written by a colleague. I was amazed at how easily we could turn code into diagrams. Since then, I've been using it every time I want to explain something as a diagram. It can help create many types of diagrams, but today I'll focus on the sequence diagram.
Let's briefly go over what the sequence diagram is...
It's a type of diagram that shows how actors or objects interact with each other in a time sequence. Umm... It might sound a bit too brief, but let's look at this example
I ask my brother to make me a coffee ☕
We can draw a simple sequence diagram like this
sequenceDiagram actor I actor My brother participant Coffee machine I->>My brother: Hey! Make me a coffee My brother->>Coffee machine: Walk to Coffee machine->>Coffee machine: Make a coffee Coffee machine->>My brother: Coffee's ready My brother->>I: Take coffee
In this diagram, my brother and I are the actors, and the coffee machine is an object. The line with an arrow shows the interaction between the actor and the object. It's easy to understand, right?
Why Mermaid?
As mentioned earlier, using a mouse to draw diagrams on an online whiteboard was too challenging. Even with other drag-and-drop tools, it can still be time-consuming.
Mermaid is a tool that helps generate diagrams using code-based input (diagram as code). Here's what the code looks like for the above diagram
123456789sequenceDiagramactor Iactor My brotherparticipant Coffee machineI->>My brother: Hey! Make me a coffeeMy brother->>Coffee machine: Walk toCoffee machine->>Coffee machine: Make a coffeeCoffee machine->>My brother: Coffee's readyMy brother->>I: Take coffee
Tada! 🎉 I guess you can probably map each line of code to the diagram easily. But let's go through it together
- I defined two actors (My brother and I) and a participant (or object), the coffee machine
- The syntax of the lines below is in this pattern [origin][message][destination]: [message text]
- The origin => What creates interaction
- The destination => What receives the interaction
- The message =>How they interact
Let's see another example, what if my brother isn't in the mood to help me make coffee?
sequenceDiagram actor I actor My brother participant Coffee machine I->>My brother: Hey! Make me a coffee alt He's in a good mood My brother->>Coffee machine: Walk to Coffee machine->>Coffee machine: Make a coffee Coffee machine->>My brother: Coffee's ready My brother->>I: Take coffee else My brother->>I: Make it yourself. I'm not your barista. end
We can also add the alternative (if/else) to our diagram, which is generated from the below code
12345678910111213sequenceDiagramactor Iactor My brotherparticipant Coffee machineI->>My brother: Hey! Make me a coffeealt He's in a good moodMy brother->>Coffee machine: Walk toCoffee machine->>Coffee machine: Make a coffeeCoffee machine->>My brother: Coffee's readyMy brother->>I: Take coffeeelseMy brother->>I: Make it yourself. I'm not your barista.end
You can see more examples and syntax here
I want to use it now! Where can I use it!?
There are many ways we can use/embed the Mermaid, here are some of them
- Online editor - mermaid.live
- Install as a dependency - npm
I didn't lie to you. did I? It's really simple and quick. I hope Mermaid helps you the next time you need to create diagrams. See you in the next post! 👋🏻