A picture is worth a thousand words. Plain text can convey high levels of detail, but when there are multiple entities involved, text fails to communicate the relationships between them well. In a recent incident, I needed to explain to myself and others how information flowed between four different actors in a transaction. Oral and written attempts would quickly become confusing because of the difficulty of keeping the state of all the different actors in our heads at once. In comparison, once the transaction was laid out in a diagram, the flow of information immediately become far easier to understand for all involved. This is the power of diagrams.
However, creating and sharing diagrams can be pretty frustrating. Most tools that I’ve used have required heavy mouse-based interaction and fiddling with dragging lines here and there in an attempt to keep things looking neat. Then comes the problem of distribution: Save the diagram in its native format or export it to an image? The first option requires everyone to have the same diagramming software but retains the ability to edit. The second option makes the diagram viewable by everyone, but loses the ability to edit. Wouldn’t it be great if there was a way to create diagrams just by typing some simple markup, and have it render a diagram anyone can view? There is a way thanks to a project called Mermaid.
Even lacking the arrows, having the ability to view embedded diagrams in Markdown is fantastic, and I hope that those little pointy guys will make an appearance soon. Until then, there’s always Mermaid Preview in a dedicated pane whenever you need to see the directional arrows. This is a fantastic addition to your toolkit for creating more informative documentation.