I often get asked why I think writing code to create diagrams (i.e. "software architecture as code" ... the approach I've taken with @structurizr) is a good idea. I like this slide in @klu2's presentation. Here's some background on the approach... 
I've been teaching the C4 model (infoq.com/articles/C4-ar…) for years, and I get asked the same question at the end of every workshop, "what tooling do you recommend?". Up until a few years ago, my stock answer was, "it's all just boxes and lines, so just use Visio". 😳😄
Obviously being an unsatisfactory answer, I decided to build some tooling to support the C4 model; with the goal to create an easy to use, lightweight modelling tool (rather than a drawing tool), that takes care of as much stuff as possible (e.g. notation).
Given this was going to be a modelling tool rather than a drawing tool, you need some way to allow users to enter the structured data that makes up the model (i.e. people, software systems, containers, components plus the relationships between these elements).
I also wanted Structurizr to be browser-based, so I set about building a HTML/JavaScript web app as a prototype. The UI was basically a set of HTML forms that allowed users to enter data in a structured way.
You'd click "Add a software system", and then get a HTML form to enter the software system's name, description and other metadata. Repeat for every other element you need to add to the model. And ditto for the relationships.
One of the worst parts of traditional UML modelling tools is the UI, and specifically data entry. You end up right-clicking all over the UI, and entering element information into text boxes. I'd basically built the same thing - the UI/UX was horrible, even for small models! 😳
The funny thing here was that I had a really nice set of Java classes on the server (this was a Java/Spring MVC web app) to represent software systems, containers, components and the relationships between them ... a representation of a software architecture model ... in code!
In a sudden realisation, it occurred to me that those Java classes were potentially a much better UI for defining software architecture models. Typing "new SoftwareSystem(...)" is much quicker than clicking buttons and entering data into text boxes.
So I ditched the entire data entry UI and, for the prototype, replaced it with a single textarea where you could paste in a JSON representation of the object model that was created using those Java classes. Those Java classes went on to become this -> github.com/structurizr/ja…
This experiment proved to me that it's quicker to create models using a text-based format (in this case, code), rather than clicking around a UI and entering text into text boxes. There's still an outstanding question here about why use code instead of static text, like a DSL?
Lots of tools allow you to create diagrams using text. PlantUML, WebSequenceDiagrams, etc. While these do work well, you're still only creating a single diagram at a time, rather than a *model*. So there's no "intelligence" here; you can't ask the text definitions questions.
There are also things called "Architecture Description Languages" (ADLs), which very few people seem to use. These are DSLs specifically designed to model software systems, but the language grammar/syntax of most leaves something to be desired!
Using code to create a software architecture model has a certain familiarity about it. You do need to learn the APIs, but you don't need to learn another language, which is a problem often cited for the low adoption of ADLs.
You can also use the programming language features to easily manipulate the model; e.g. write a Java lambda to "make all repository components have a relationship with the database" or "add all elements like X to the diagram".
You also have the ability to export the model from code to any other representation ... the JSON format used by Structurizr, PlantUML definitions, or something else entirely.
The downside of this approach is that, currently, there are only implementations for Java (plus Kotlin) and C# ... so this "excludes" a large percentage of the programming community. This will change over time. Also non-coders are excluded, but they're not the target audience.
