Diagrams as code

The technique of "diagrams as code" just appeared on the ThoughtWorks Tech Radar (as "Trial"), with the Structurizr DSL also getting a mention.

Diagrams as what?

Like "infrastructure as code", "diagrams as code" is a bit misleading to be honest, as it seems to be used as an umbrella term for ways to create diagrams using a text-based approach. Some tools use real code, and others use a text-based DSL. Just bear that in mind when choosing your tooling. Whichever language you choose, everybody on your team will need to learn it in order to create diagrams.

The benefits of "diagrams as code"

Visio, draw.io, LucidChart, Gliffy, etc - not recommended for software architecture diagrams covers my thoughts on why we can do better for software architecture diagrams, and "diagrams as code" is certainly a step in the right direction. The most obvious benefits are the ability to use the text-oriented tooling we already use as software developers, text is easily version controllable and diff'able, plus many of the "diagrams as code" tools can be scripted and integrated into a build pipeline for automatic documentation generation.

Diagrams vs models

And that's a good step forward from tools like Visio, but it really only scratches the surface of what's possible. Most "diagrams as code" tooling provides a way to create a single diagram from a single textual source file. So if you need to create two related diagrams, you'll need two separate source files. Some tools do provide a way to share common snippets via "includes", but generally you have to ensure that you keep both source files in sync when you make a change to either of them. Modelling software architecture with PlantUML shows an example of this, and presents a solution in the form of the Structurizr DSL.

The Structurizr DSL is an open source project that I built during the depths of the COVID-19 lockdown earlier this year. It's a textual domain specific language for defining a software architecture model (based upon the C4 model), and essentially just a thin wrapper around the existing open source Structurizr for Java library. The first version of the DSL only took a week to build!

The Structurizr DSL is actually much more powerful than the other tools it's compared to, because it allows you to define a collection of elements/relationships (a "model"), and multiple views of those elements/relationships. This model-based approach allows you to share elements/relationships across diagrams, keeping everything in sync when you make changes. This is a very powerful concept, especially when coupled with the next thing I want to mention.

Multiple output formats

Most of the "diagrams as code" tools you'll see today are focussed on creating diagrams in one output format, via one input format. If you define a diagram using the PlantUML diagram syntax, you'll need PlantUML to render that. The same is true for Mermaid, WebSequenceDiagrams, and the Python-based "Diagrams" tool. Use those input formats and you're locked into using those tools to render your diagrams.

The Structurizr DSL is very different. The text-based DSL used to define a model and views is tooling agnostic, and the open source Structurizr CLI provides a way to render those views as diagrams using a number of tools; including the Structurizr web renderer, PlantUML, Mermaid, WebSequenceDiagrams, and Ilograph. Each rendering tool provides something slightly different, so the Structurizr DSL is a fantastic way to try a number of diagramming tools without being locked in to any of them. Getting started with the Structurizr CLI shows this in action.

Humans vs computers

One of the assumptions most people make about "diagrams as code" is that these text-based diagram (or model) definitions are authored by humans. And that's how the majority of teams use these tools at the moment. But, again, we're only scratching the surface of what's possible here. Rather than writing the code/text yourself, what if a computer was to do this for you? Perhaps it could parse your AWS CloudFormation definitions, and automatically generate your cloud architecture diagrams via PlantUML, Mermaid, or the Structurizr DSL.

There isn't much tooling available to support this type of use case yet, but as adoption of "diagrams as code" increases, I'm certain we'll be asking tools to do the hard work for us. It'll be interesting to see how this space evolves over the next few years.

Summary

I've been advocating "diagrams as code" since the I released the initial Structurizr for Java library back in 2014, so it's great to see the general concept appear on the ThoughtWorks Tech Radar. I've certainly seen many of the organisations that I work with either adopt this already, or they're looking at better approaches to creating long-lived documentation. "Diagrams as code" is definitely worth trialling if you've not looked at it yet, and the Structurizr DSL demo is a great way to get started.