I stumbled on a Twitter thread by Ross Kaffenberger, a senior engineer at StitchFix. He discussed the need for diagrams in software engineering, especially in larger organizations where an understanding of the entire system can’t live in a person’s head. Or even in the heads of multiple people.
When my career started, it wasn’t uncommon to have 3-ring binders filled with hand-drawn flowcharts outlining system processes. These were designed before the code, not as documentation after the fact. To me, having diagrams feels like a no-brainer.
Visio was, for many years, the go-to application for creating diagrams in Windows. I remember the awe I felt the first time a line segment between two shapes moved around another object between them. I didn’t have to do it manually? Sweet!
That’s a bit of standard fare in most tools today. If I need to put together something today, I’ll use Lucidchart. But Lucidchart has the same fatal flaw that frustrated me with Visio. I spend more time fixing the automated collision detection than drawing what I needed in the first place. The tools can become more of a hindrance than a help.
In his thread, Ross mentioned a simple diagramming tool called Mermaid.js. This javascript library lets you describe diagrams using simple text and code. While it may not solve the layout problems I mentioned above, its simplicity is what makes it shine. The simple syntax allows you to create a document in very little time, and because it’s text-based, I don’t have the compulsion to manipulate the diagram to get it “perfect.” Checking the diagram into source control isn’t a bad idea either.
I haven’t yet used Mermaid for a production-level project, but it has my attention.