Diagram as Code

Introduction

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.

Options

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.
• Mermaid: is a Javascript-based diagramming and charting tool. It supports many types of diagrams and is natively integrated into GitHub. One disadvantage might be that it is less established and has fewer diagram types than Plant UML. There is support for the C4 model, but unlike the multiple-view approach from Structurize, you must create multiple diagrams for the different C4 viewpoints.

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.

Mermaid

Although Mermaid is younger than PlanUML, it still has many diagram types and integrations.

Examples

Many of the ad-hoc diagrams simply need boxes and arrows. You will typically use the Mermaid flowchart diagram type for those:

flowchart TB
    c1-->a2[Example text]
    subgraph one
    a1-->a2
    end
    subgraph two
    b1--arrow text-->b2
    end
    subgraph three
    c1<-->c2
    end

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):

sequenceDiagram
    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
    end
    opt Extra response
        Bob->>Alice: Thanks for asking
    end

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.

Conclusion

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.

Resources

• 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