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. 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. It'll be interesting to see how this space evolves over the next few years. 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. 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. But, again, we're only scratching the surface of what's possible here. And that's how the majority of teams use these tools at the moment. One of the assumptions most people make about "diagrams as code" is that these text-based diagram (or model) definitions are authored by humans. Getting started with the Structurizr CLI shows this in action. 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. 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. Use those input formats and you're locked into using those tools to render your diagrams. The same is true for Mermaid, WebSequenceDiagrams, and the Python-based "Diagrams" tool. If you define a diagram using the PlantUML diagram syntax, you'll need PlantUML to render that. Most of the "diagrams as code" tools you'll see today are focussed on creating diagrams in one output format, via one input format. This is a very powerful concept, especially when coupled with the next thing I want to mention. This model-based approach allows you to share elements/relationships across diagrams, keeping everything in sync when you make changes. 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. The first version of the DSL only took a week to build! 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 Structurizr DSL is an open source project that I built during the depths of the COVID-19 lockdown earlier this year. Modelling software architecture with PlantUML shows an example of this, and presents a solution in the form of the Structurizr DSL. 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. So if you need to create two related diagrams, you'll need two separate source files. Most "diagrams as code" tooling provides a way to create a single diagram from a single textual source file. ![]() 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.Īnd that's a good step forward from tools like Visio, but it really only scratches the surface of what's possible. 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. Whichever language you choose, everybody on your team will need to learn it in order to create diagrams. Just bear that in mind when choosing your tooling. Some tools use real code, and others use a text-based DSL. 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. The technique of "diagrams as code" just appeared on the ThoughtWorks Tech Radar (as "Trial"), with the Structurizr DSL also getting a mention.
0 Comments
Leave a Reply. |
AuthorWrite something about yourself. No need to be fancy, just an overview. ArchivesCategories |