Creating diagrams is essential for understanding and discussing complicated structures and processes in software development, but creating and maintaining them can be tedious and sometimes frustrating using What You See Is What You Get (WYSIWYG) diagram tools. I have lost count of the number of hours spent dragging around and “fighting” with those tools. The total freedom of drawing expression comes at a cost. Some of the tools break down as the diagrams get large.
Diagram as Code
Diagram as Code is a methodology where diagrams are created, updated, and managed using code or simple text instructions. This approach offers several advantages over the WYSIWYG alternatives:
- Creating complex diagrams is easier and more efficient, as you can simply write or change a few lines of code
- Ensures consistency across diagrams
- It makes version control and collaboration easier
The main focus of WYSIWYG is the layout, and you do not care about the underlying representation. Diagrams as code flips this around.
Github Copilot is able to create diagram suggestions based on your context. I have found myself describing a process with multiple steps and having GitHub Copilot suggest a correct diagram as code representation of it.
In my current project, we investigated a couple of diagrams as code options:
- Plant UML: is a tool that allows you to draw UML diagrams using a simple and intuitive language. It requires a Java runtime environment and can be cumbersome to set up compared to other options. Plant UML has been around since 2009 and is the oldest of the options I evaluated.
- Structurizr: allows you to create software architecture diagrams and documentation based on the C4 model. One of the powers of Structurizr is its ability to create multiple representations/views from a single model. It is only limited to the C4 modeling model.
We landed on mermaidjs since it is natively integrated into GitHub; thus, there is no need to install any plugins or extensions. Mermaid has all the diagram types we need.
Many of the ad-hoc diagrams simply need boxes and arrows. You will typically use the Mermaid flowchart diagram type for those:
The diagram type that probably saves you the most time updating, compared to WYSIWYG options, is the
sequence diagram. Imagine having the following diagram(example from the mermaid documentation):
Alice->>Bob: Hello Bob, how are you?
alt is sick
Bob->>Alice: Not so good :(
else is well
Bob->>Alice: Feeling fresh like a daisy
opt Extra response
Bob->>Alice: Thanks for asking
Then, you need to make a change by introducing another alternative. In diagram as code tools, you simply add it and make the rendering tool do the heavy lifting, aligning lines, moving all boxes to make room, making sure the line text is centered, etc.
The Diagram as Code methodology eases the creation and maintenance of diagrams for software development processes. It not only ensures consistency across diagrams but also enhances efficiency in creating complex ones. This approach simplifies version control and collaboration and enables a more streamlined and less frustrating experience than traditional WYSIWYG tools. While various tools, like Plant UML and Structurizr, exist, we found Mermaid to be the optimal choice due to its native integration with GitHub and a wide range of diagram types.
- For the Visual Studio Code, you can use the https://marketplace.visualstudio.com/items?itemName=bierner.markdown-mermaid plugin.
- https://mermaid.live/ provides rendering in the browser. Perfect for quick collaboration, where you do not need to install anything