Technical diagrams are a central part of modern software engineering. Whether it is a C4 architecture model, a sequence diagram or any flavour of UML, we interact with these pictures on a daily basis.
I imagine that as a collective company, Entelect has drawn enough lines-and-boxes to get to the moon and back many times over!
It's easy to think that these diagrams are the ultimate specification of all technical requirements, integrations and features. We pour hours into crafting the perfect diagrams and yet they always fall short in some way. Surely if we could just define the perfect diagramming notation we could describe any software requirement perfectly? (Spoiler... we've tried, it's called TOGAF, and its diagrams almost always unintelligible to everyone including the author).
This is because there is a fundamental limit as to how much information can be packed into a diagram.
Diagramming tools often provide static representations at a moment in time. This makes it difficult to understand how changes in one component might impact others over time.
Diagrams often lack the context needed for complete understanding requiring increasingly complex supplementary information. The only way to break this limit is through the narrative of your explanation.
Humans love stories, and live their lives through them, from our rich oral histories of our ancestors to Netflix and the gossip around the watercooler. Exploit this in your explanation of your diagrams.
Take time to set the scene. Introduce the actors and systems, give history as to how they came about and the constraints they've had to evolve through. Share experiences of how they interact with each other and their relationships. Speculate on how they may grow in the future.
A compelling story's architecture involves a clear beginning, rising action, a climax, falling action, and resolution, creating a satisfying narrative arc that engages the audience.
The diagram itself isn't the important artefact. Rather, it is the shared understanding you create around it.
So next time you're drawing your lines-and-boxes, take a few moments to think about how you're going to tell your story...
Yours faithfully, Matthew van der Velden,
Solutions Architect
