A LinkedIn post about C4 diagrams got me typing up a reply that got too long. I figure I’d plop it down here.

This is why I spent a lot of time in Lucidchart the most awesomest diagramming tool out there (don’t even try Figma, FigJam actually, Figma’s solid!). It was the only thing that would allow me to translate what I saw to a visual representation of the system. And more, it can publish live documents and images. Change the diagram, the image changes wherever it was embedded. Critical!

When C4 emerged, we started using IcePanel, an adapted version of C4, which let me make C4 diagrams that were actually “projections” of the underlying model of objects and connections. The same “container” with connections to others, could show up in many diagrams. Delete it, and it’s gone from the model along with all the connections, AND all the diagrams. So it became a living persistent representation of our system. A rectangle wasn’t just a rectangle anymore. Structurizr being another C4 diagramming tool made by the inventor of the C4 model Simon Brown.

If you are “diagramming” and not “modeling”, just stop. If you think docstrings and documentation get out of date fast, try a PNG in a Confluence doc, Google Drive folder, or a slide presentation. The minute you hit “Export”, it’s over. And if you create different projections of models of components for different audiences, you get completely unrelated rectangles. Now you have an exponential growth of maintenance hell even just to change the name of the component.

But even with C4 modelling, as the infra and code grows and changes, the risk of unmaintained appendages is high. And diagrams are not self explanatory. There are studies on how people learn and understand visuals, but I won’t go into it here. Just remember the term “Infographic”!

These days, we have an additional player that can serve to bridge the gap and maintain the gestalt. Agents are already helping to maintain sync between models and code. Now, we can get closer to a solid source of truth throughout the timeline keeping documentation, code, and diagrams stay in accurate and valuable.

How this all plays out remains to be seen, but the opportunity is there for making teams and systems stronger and fighting the cruft and the tech debt that came before.