⚡ TL;DR
- Diagram-as-code (aka architecture-as-code or AaC) is a way to create diagrams from code instead of manually.
- The perceived benefits of diagram-as-code include easier creation, versioning, and integration into build pipelines.
- The tradeoffs include a higher learning curve, less accessible collaboration with non-technical audiences, and less flexibility.
- Diagram-as-code isn’t a silver bullet solution to documentation. However, combining diagram-as-code with manual methods can be an effective way to communicate software systems at different levels of complexity.
🚀 Introduction
A few months ago, we came across a spicy thread on the software architecture sub-Reddit about diagram-as-code. It struck a chord in the community, with people sharing opinions, both in support and against it.
This topic often comes up with our customers on IcePanel, so we thought we’d share some thoughts on this and where we think this movement is heading.
🧑💻 What is diagram-as-code?
Diagram-as-code (sometimes referred to as architecture as code or AaC) is a way to create diagrams using code instead of manually creating them by hand or using a drag-and-drop tool. Typically, the code uses domain-specific languages (DSL), which are simple programming languages built for diagramming. There are several DSLs to choose from on tools like PlantUML, Mermaid, or Structurizr.
If you’re looking for a breakdown of options, see our article on the top diagram-as-code tools here.
💡 The promise of diagram-as-code
Creating software architecture diagrams is a tedious process. The reality is most technical people don’t want to spend a lot of time manually manipulating boxes and lines to make things look pretty. They want to build, analyze, and make important architectural decisions — the hard things that require deeper thinking. However, once systems reach a certain scale and complexity, documentation becomes essential. People want documentation with minimal effort. They want their cake and to eat it too.
This is where diagram-as-code came in as a promising solution. Diagram-as-code aimed to drastically improve the ease of creating diagrams, maintaining, versioning, and collaborating on architecture designs. Diagram-as-code was seen to have several key benefits, such as:
- Automation: Diagram as code could be automatically created from code changes and stay in sync with architectural changes.
- Integration with CI/CD pipelines: Diagrams could be automatically generated and validated in a CI/CD pipeline without a manual step in the development lifecycle.
- Version control: Diagrams could be automatically versioned with source code, making it easier to track changes or revert back to previous versions.
- Improved collaboration: Most developers and architects prefer not to use another dedicated tool, so having everything integrated into a developer platform was seen to encourage more collaboration.
- Scalability: Large and numerous diagrams become difficult to manage over time. Diagram-as-code enabled teams to manage this scale effectively compared to manual methods.
There were a lot of perceived benefits, but what have been the results so far?
🤬 The challenges with diagram-as-code
In theory, diagram-as-code was seen as the silver bullet solution to software documentation, but results have been mixed. We’ve worked with hundreds of customers, some of whom have tried to adopt diagram-as-code only to run into challenges.
These challenges typically fall into a few categories:
- High learning curve: Developers and architects are forced to learn a new syntax, which takes time and company-wide education. Non-technical people also have a much more difficult time learning the syntax.
- Collaboration is limited: Although these tools could be easily integrated with developer platforms, these platforms weren’t specifically designed for interacting with diagrams in detail. They also aren’t as accessible to non-technical audiences. This siloed architectural context within technical teams.
- Lack of flexibility: Most diagram-as-code tools produced static diagrams with little interaction or ability to reposition objects or connections.
- Integration challenges: Many DSL languages had limited support across popular IDEs and CI/CD platforms. Teams were locked into specific tools or building custom integration solutions.
The reality is that diagram-as-code comes with its own set of tradeoffs, just like using manual methods does).
erDiagram
CUSTOMER }|..|{ DELIVERY-ADDRESS : has
CUSTOMER ||--o{ ORDER : places
CUSTOMER ||--o{ INVOICE : "liable for"
DELIVERY-ADDRESS ||--o{ ORDER : receives
INVOICE ||--|{ ORDER : covers
ORDER ||--|{ ORDER-ITEM : includes
PRODUCT-CATEGORY ||--|{ PRODUCT : contains
PRODUCT ||--o{ ORDER-ITEM : "ordered in"Example syntax for a diagram in Mermaid
🔮 Where are we heading?
Despite the tradeoffs that come with diagram-as-code, it isn’t going away anytime soon. The need to understand complex systems and the effort required to align teams is too high. With the advances in AI that can generate code from prose, new solutions are now becoming possible (we have a few opinions on AI for diagram creation as well, which we’ll share in a future post).
We prefer to be doubtful about any particular prediction about the future. It’s easy to get caught up in the hype, which often promises some flavour of automation. With that said, we see a world where the design and documentation of software systems combine elements of diagram-as-code with manual methods.
One of the reasons why we don’t have a Level 4 Code diagram in IcePanel is because the effort to reward in creating them is low. Things like class diagrams take a long time to create by hand and get out-of-date quickly as code is constantly evolving. Now, with the possibilities of AI and diagram-as-code, perhaps there’s an opportunity to automate lower-level views but have higher-level diagrams (which require more abstract thinking) created manually. We’re also particularly excited about the possibilities of connecting architecture to real things, from the code itself to deployment entities. We have many ideas here to surface useful information in diagrams automatically from things in real life, so your diagrams are a closer reflection of the systems in production.
All this to say, we’re excited about the possibilities of helping teams collaborate more thoughtfully around complex systems. We plan to continue exploring the possibilities of finding fun and useful solutions to help architects, developers, and non-technical people design their software architecture.
What have your experiences been like if you’ve ventured into diagram-as-code? We’d love to hear your thoughts. 😎
