Diagrams as Code 2.0 • Simon Brown • GOTO 2021

This presentation was recorded at GOTO Copenhagen 2021. #GOTOcon #GOTOcph

Simon Brown - Author of "Software Architecture for Developers" & Creator of the C4 Software @simonbrown4821

ABSTRACT
Diagrams as code is becoming a popular way to diagram software architecture, particularly for long-lived high-level documentation. You write the diagram source in a text-based domain specific language (e.g. PlantUML or Mermaid) or a programming language, and render diagrams using web-based or command line tooling.
The benefits are well understood – writing the diagram source as text allows for easy integration into software development practices and toolchains, plus the automatic layout facilities allow authors to focus on content.
The problem with this approach is that it's easy for diagrams to get out of sync. Enter "diagrams as code 2.0" — a way to define a model of our software architecture and the views that we'd like to see, ultimately resulting in a consistent set of diagrams that are generated for us. [...]

TIMECODES
00:00 Intro
02:09 C4 Model
06:05 Diagramming vs modelling
07:54 Domain concepts
08:41 Model-based (DRY)
12:41 HTML & CSS
15:44 Diagrams as code 1.0
16:02 Diagrams as code 2.0
20:13 More advanced features
24:04 Enterprise-wide modelling?
25:09 Scripting support
26:36 Plugin support
28:58 Custom tooling
30:23 Usage scenarios
31:24 Interactive diagrams
35:19 Closing thoughts
38:49 Outro

Download slides and read the full abstract here:

RECOMMENDED BOOKS

#SoftwareArchitecture #DevOps #SimonBrown #Microservices #Monolith #ModularMonolith #Complexity #BoundedContext #C4Model #SoftwareEngineering #Programming #SoftwareDevelopment #UML #DRY #Structurizr

Looking for a unique learning experience?

SUBSCRIBE TO OUR CHANNEL - new videos posted almost daily.

[davidhsieh]

This sounds like a dream for Software Architecture diagramming in general. Thanks Simon Brown!

[CosasCotidianas]

I've used an online UML diagram tool that uses this principle (and I think the same language). Loved it. The time saved definitely justifies its usage, and the learning curve is pretty straightforward.

[dandoescode]

Awesome presentation Simon! I've been using PlantUML for a while and more recently Mermaid. I love the idea of separating the model from diagrams. I found creating lots of diagrams for the same system is definitely not DRY and only gets worse over time. Have had a brief play with Structurizr Lite via the docker container. Works like a charm!

[JadedEvan]

I would enjoy seeing a case study on the efficacy of what he's proposing here. The big barrier I experience with my team is ongoing maintenance for diagrams and general opposition to even documenting to begin with. Would be cool to see some real life examples of start up / scale up teams and how they use this model. Insightful presentation!

[sitryk]

Every project idea I've ever had seems to just come into existence before I can start on it.

[david.thomas.]

Some excellent work there. Interesting stuff and worth looking into further. Great presentation!

[alokmtu]

Love C4, PUML and diagrams as code in general. Will give structurizr docker & CLI a spin 👏🏼

[amananwari]

Thanks Simon, In fact I developed small tool to generate plantuml from my own dsl expressed in json to solve the problems of diagramming versus modelling. And had following listed features to implement in future but never got it, looks like you have done all of it. Thanks, looking forward to use it.

· Convert C4 architecture as code

· Determine aspects such as below not as text, rather have their own meaning to easily search
o Security (Authentication, Authorization, ports etc.) are well defined and understood.
o Infrastructure tags such as network zone, nsgs, vnets, load balancers, fail over etc.
· Automatic architecture review implementation, may be embed with DevOps pipeline.
· Generate Visualization automatically to better understand architecture.
· Show entire architecture evolution (roadmap) with different milestones, possible animate it.
- Associate architecture decisions with architecture.

[aardrock]

Like:
- interactive, zoomable and ‘disposable’ hierarchies — exploring a (system’s) structure becomes ‘free’ and affordable;
- easy to create, maintain, evolve, keep consistent, complete, coherent
- model-based (DRY)
- form and content separated (themes; like “The Zen of CSS Design”)
- notation independent
- open source
- diagrams are disposable (like Observable’s “viz for ‘free’”)
- DSL for hierarchy viz
- can be generated (e.g. from augmented source code)
- C4 model for gearing different (architecture) stories to different audiences
- diagrams are maps (the map is not the territory :wink:
- version controlled
- like MVC for navigating and viewing (archtectural) structures (in order to understand and possibly improve them)
- style specific abstract elements in the structure (e.g. system, user, etc.)
- accept inputs from other sources
- can generate formats for PlantUML, Mermaid, etc.
- support hybrid of automatic and manual layout
- uses Markdown for texts

Wishes:
- Observable adopts a theme approach as well: e.g. you can create a theme and use it to viz a hierarchy (that goes beyond the default; just like CSS (visual) and HTML ((hierarchical) structure)
- may be a visualizer for notebooks, in fact, for Observable itself, like

[MrDebranjandutta]

I wonder whether he's seen Unreal Blueprints, it would be great if someone could port that for a general programming environment instead of being restricted only to games.

[iirekm]

Unfortunately, I can't see any real value of this tool in real projects:
- many diagrams are created by non-tech people, and they probably won't want to learn a DSL, they prefer e.g. Visio, Enterprise Architect or diagrams net
- for tech people, diagramming DSLs existed for long, e.g. .dot language or JavaScript libraries. They can be easily embedded in popular tech doc tools (like Markdown)
- diagrams are great for high-level introduction to project (e.g. new employees, or new customers), but for low-level things like algorithms, a few lines of code tells a better story than even the best diagram
- many tools can generate diagrams from real, production code (e.g. intellij can generate UML, Pulumi can generate .dot diagrams)

[art.]

I am a newbie on software development (coding expirience over 3 years) and i am trying to develop a cloud based OS System (whatever, does not matter).

However, it seems like c4 level architecture with it's dsl could be implemented as an emacs library or major mode? This general purpose of it as a text based architecture module seems to be the perfect match with the emacs enviroment. What do you think?

[devopmh]

great talk, despite I prefer to use something like cdk, terraform or pulumi to use such as diagram as code xD

[ahoe]

Why write autolayout for automatic layout? Would be better if the program uses autolayout when no layout is specified.

[holgerwinkelmann]

what you think about integration with d2lang and terrastruct?

[victormendoza]

Probably cool, but in my eyes just pay for lucidscale and focus on something else unless docs are that important.

[higiniofuentes]

I use Yourdon-Demarco diagrams system to work with, I found C4 too verbose and not to the point and for an user/customer too intimidating. Your proposal seems a bit less complicated to presented to general public!

[carlosluisquesada]

Loved the premise. You lost me at “hierarchy”.

[markemerson]

Imagine using the same zoom in tech that NFTs use…

[bob-nykn]

Inventing a "need" for a useless widget.