I have a core memory of a meeting I was once in. We were thinking about the design of a system, and I happened to have made a simple diagram before the meeting for another reason. It was a reallysimple diagram — literally three boxes in a row.
A few minutes into the meeting, it seemed like there was some misunderstanding about the system. I realized that the diagram might be useful, and I put it on screen. By the end of the meeting every person had ended up commenting about what a helpful diagram it was. Except, it wasn’t a compliment like “what an amazing diagram!”. It was more like we were laughing to ourselves: “I can’t believe I’m referring back to this simple three box diagram again, but it’s really helping”.
I’m not telling this story because I’m super cool for having made a diagram. The story stuck with me because I was surprised that such a simple diagram ended up being legitimately useful to a group of smart people. It felt like putting a penny in a machine and getting $100 out.
The lesson is that visual communication is important. Half the human brain is involved in processing visual images. A very simple diagram can communicate a lot of information because our brains are so good at processing images. This is why we have a common expression of “a picture is worth a thousand words (although as an engineer I appreciate the position that the correct ratio is “one picture, 1.77 million words” assuming 256 values per pixel and so on…).
More evidence that visual communication is important and special is the example of cave paintings. Researchers consider cave paintings to be a form of educational technology that goes back at least 40,000 years. Drawing a diagram is one of the oldest communication tools that we still use today. Sometimes when I’m using a whiteboard to explain or brainstorm, I get a laugh that we’re still here, drawing on walls.
When it comes to software engineering, diagrams seem even more essential. We aren’t working on a physical machine where we can point at the parts. It’s possible to read code and develop a mental model of the system, but that takes days and weeks. If we create a representation of the code with a diagram, it can take minutes to develop that mental model. The added information bandwidth is like comparing dialup modem vs gigabit.
A good culture of diagrams is good for business. It makes meetings more efficient, avoids misunderstanding and conflict, insures against team members leaving, makes onboarding new team members easier, and helps scale communication for large (100-1,000 person teams).
One of the other reasons I think it’s important to feel comfortable producing diagrams is because doing so is a powerful learning tool. The act of creating the diagram causes you to process the information more deeply, and make it easier to remember because making diagrams engages the visual and spatial parts of your brain. This effect is so strong that it is the basis for a technique used to memorize large chunks of information, used for memorizing sequences of over a thousand unrelated numbers.
Do you have any tips for making good diagrams?
If you aren’t routinely drawing diagrams when planning, just start doing it. That’s my #1 tip. Making diagrams is easy, but developing the habit might be harder. If you don’t feel fluent with diagramming software, just draw on a whiteboard or piece of paper and take a picture of it. The tool itself doesn’t matter very much, and it’s frankly ok to have low-fidelity diagrams. Remember our industry was built by drawing on bar napkins. Something is better than nothing, and you’ll constantly get better.
If you are making a diagram that’s going to be reused heavily, presented to people outside your immediate team, or has more than ~20 boxes, you should add extra formatting and other standard advice of “how to make a diagram” that you’ll find on Google. Use icons, colors, and headings which all improve clarity, and they also make your diagram look polished. In contrast, if it is a throwaway diagram for a single meeting, it’s ok to skip these things.
Most importantly, I’ve noticed that the number one blocker is “what do I put in the diagram” because the answer is “it depends”. If you’re talking about software components, should you include a firewall in the diagram? Do you need to mention the data center location or not? Do you need to specify a generic “storage” component, or do you need to be specific about the storage provider and configurations? It’s really easy to get stuck at this point…
The best answer I’ve found comes from Simon Brown who created the C4 Model. The central idea is that it’s impractical to create one diagram that can fully represent everything, in the same way that it’s not practical to make a single map that can represent a place. He compares it to Google Maps, where more detail starts to appear as you zoom farther in.
Simon’s logical conclusion is to create more than one diagram. Start with a high-level diagram that’s almost too obvious, and then pick the component you’re talking about and make another diagram that is “zoomed in” to that component, and then continue zooming in as many times as you need.
For example, I can tell you we need to talk about “updateComputedAttributes”, but that may or may not be meaningful. In contrast, a zoomable diagram makes it trivial for anyone to understand useful context at each level:
You can already see that updateComputedAttributes is probably some kind of function that occurs during a create or update action while persisting to the DB.
The extra context (both vertical and horizontal) is an improvement in usability/readability for technical and non-technical stakeholders. Especially when you have to work across multiple teams who don’t know each other’s domains closely, a diagram like this can cut hours off complex meetings and prevent costly misunderstandings.
I think there is also a subtler process benefit. The C4 model represents a straightforward and logical process for producing diagrams. It’s easy to feel stuck if you have to make a complex diagram from scratch, but the idea of a zoomable diagram that starts at a high level makes it feel easy to start. Easy processes get used and followed more often than hard ones, which means having a simple process to make diagrams will result in better communication.