One Diagram to Rule Them All (Please Don’t)
The Scene
You open up the architecture diagram, immediately suck air through your teeth, and mumble “Oooh boy…” under your breath. The Architect has just sent you, the NewPerson(tm), the current architecture diagram. It looks more like a New York City street map. Your brain is already starting to hurt. You reach for your coffee mug, but it is cold and bitter.
“Don’t panic. It’s quite straightforward,” says the Architect that drew it. Yes, of course. It all makes sense… to the person that already knows how it works!
Introduction
Some architecture diagrams are in the “One Diagram to Rule Them All” format. The Architect has painstakingly annotated every little bit of detail needed. Everything you need to know is right there.
These diagrams are drawn with noble intent but are not helpful. The purpose of an architecture diagram is to lead the reader to an understanding. If the diagram is incomprehensible, it is of no benefit. Only after understanding how it all works can these diagrams make sense. By that point, the diagram isn’t helpful.
I’ll admit I have created a number of these diagrams myself. One was so detailed and complex that it was known internally as the ‘Scary Diagram(tm)’; it was more shock value than a valuable artifact.
Architects are, among many things, communicators. We are there to communicate vision. To break complex problems down and describe how to solve something. We are custodians of documentation on how things work. This means we are responsible for ensuring that what we write and draw informs the reader.
This material exists for people who don’t understand. Yet. Any complex software can’t possibly be described with a single diagram. Knowledge is based on layers. Like the strata in a rock formation, each layer builds on the one below it.
Each diagram tells a particular part of the story, and you need to focus the diagram on what you’re trying to convey. To eliminate distractions, you must remove as much detail as possible of things already understood.
Encyclopedia Britannica (and others) used to publish fantastic books on Anatomy that allowed the reader to peel away transparent layers to show anatomy underneath.
This allowed the reader to focus on a particular area but still see its context. Some architecture drawing tools will enable you to layer diagrams, but they still feel clunky for the reader.
You’re going to need a ̶b̶i̶g̶g̶e̶r̶ ̶b̶o̶a̶t̶ more diagrams.
Common Problems
Here are some things to consider to avoid some common problems.
Audience
Think of the audience of this diagram. Who is this diagram for? What do they know? What do they not know yet? Set the context of the prerequisites you expect the reader to have. Point them to previous diagrams that underpin it.
Purpose
Have a key idea of what your diagram is trying to convey. Write this down in words. e.g., “Describes the key networks, their roles, and the relationships between them.” This will help you focus on what to put in and, importantly, keep your eye out for things to leave out.
Consistency
Ensuring you maintain a standard style aids the reader by allowing their subconscious to process similar concepts quickly. Consistent colour, style, and shape provide a robust foundation for transferring knowledge. If you are building in a Cloud Service, use their standard templates/objects. All of these common patterns make it easy to comprehend the diagram.
Mixing concerns
One of the more common “Too Much Going On” problems I see is trying to mix Physical (e.g., network) relationships with Logical (e.g., services). Packing these all together takes you down a rabbit hole quickly. Create a diagram that scopes your boundary and significant networks and describes the relationships and roles these networks are there for. Then use another diagram to describe the pieces that live inside your boundary. This allows you to focus your diagram on describing the relationships between services without having the network detail complicate the picture.
The Solution
Architecture diagrams form an information hierarchy. Each diagram needs prerequisite context, that which is presumed to be already understood. This is why we have abstractions in software development to quickly communicate higher-order concepts in smaller pieces.
I highly recommend Barbara Minto’s “The Pyramid Principle.” While focused on writing, it articulates sound principles of structuring communication which I would argue includes these diagrams.
When communicating something meaningful, the diagram should visually focus on that concept. Try to eliminate everything else. Leverage the power of previously presented diagrams or common knowledge to provide the implicit context. If you feel something unrelated is essential, it may be a sign you need another diagram to support this one.
Consequences
This takes effort. There’s no getting around it. Overloaded architects, I hear you. While we, as architects, are responsible for ensuring these diagrams exist, it doesn’t mean we have to be the ones to create them.
Another responsibility of architects is mentoring. Why not crowdsource these diagrams to less experienced engineers? Give them opportunities to practice the craft of diagramming. Set guardrails on style, communicate your need, review, and give feedback. Use this as an opportunity to build relationships with people in your team. Give them responsibility and accountability to be part of the bigger picture. Use this opportunity to help them grow their career.
Have your diagrams reviewed by qualified colleagues who already understand the content (for accuracy) AND those unfamiliar (for effectiveness).
Before drawing that first box, take time to plan out and define your diagram’s purpose. Be clear about what you are trying to say.
Don’t say too much; say it in other diagrams.
