Tips for creating better architecture diagrams

At Cazoo we use some sort of visualisation almost every day, whether it’s an event storming board, architectural diagrams or sometimes just generic boxes to help categorise our thoughts. We also love our white-boarding sessions, their visual nature makes it easier to create a shared understanding, leaving minimal space left for ambiguity or misalignment.

Why is it important to draw better diagrams?

It’s all about effective communication. An ineffective diagram will have the same properties as an ineffective presentation, speech or an article. It will be ambiguous, vague or confusing for the intended audience. If you want to create useful visualisations it’s vital to make sure the content is well understood by whoever is looking at it.

Architecture diagrams in particular present visualisations for domains, systems, deployable components or databases. Here are some tips to help create effective architecture diagrams.

Tip #1 Create your own toolbox

It’ll be easier for people to understand when you use standard diagram types and your audience already know the notation framework. People you collaborate with will appreciate the predictability and familiarity of your visualisations. We often use the C4 model for our architecture diagrams. It’s also helpful to mix and match diagrams from different frameworks and create your own toolbox. Maybe your preference is context and container diagrams from the C4 model; sequence and activity diagrams from UML and event storming. Choose your own notation frameworks and your favourite types of diagrams. Build your toolbox and be as consistent with it.

Tip #2 Always add a title and a legend

This is probably the most underrated point.

The meaning of a solid line, a dotted line or a dashed line could be different depending on the context of your diagram. Using a legend communicates those meanings clearly.

A title is helpful to communicate the purpose of your diagram. If it’s to help solve a problem, state the problem it’s trying to address eg. Insurance Refunds Container Diagram. If it is to visualise the architecture of an existing system, state the name of the system eg. Payments Service Context Diagram. The first part describes the domain and is important to set the context. The second part can be helpful when there are multiple diagrams and your audience will have to spot what is relevant to them.

A legend and a title will make your diagram self-describing. It will mean your audience will ask fewer notation related questions and be able to quickly move on to discuss the real problem at hand.

Tip #3 Make your elements self-descriptive

Add a brief description to all of the elements in the diagram. That helps your audience understand the role of each component or system you have in your diagram. A single sentence is usually enough for systems or deployables, and a few words should be enough to describe a relationship.

Tip #4 Colour code generously

Colours are a great way to distinguish between different elements in your diagrams. For instance, you could use different colours to distinguish an existing deployable and a proposed new one. You could also use colours for third party systems or to identify the systems out of your immediate focus. Don’t forget to update the legend to describe the meaning of the colours you are using.

Tip #5 Detailed isn’t always better

You don’t always have to go into really granular detail on your diagram. Know your audience and what you’re trying to communicate. If your audience are business stakeholders use a zoomed out view such as a C4 context diagram and talk about systems and domains. If your audience are reasonably technical you can use a C4 container diagram to talk about deployables. High level diagrams are generally helpful to get a shared understanding relatively quickly.

Tip #6 Accuracy isn’t always better

Be ruthless about omitting information that’s not directly useful even if it’s at the cost of loosing a bit of accuracy. The more comprehensive the diagram is, the more difficult it becomes to communicate your point. Make your problem area clear and remove anything that’s not helping you communicate exactly that.

Tip #7 Create problem specific diagrams

It’s always useful to have a diagram of an entire domain or sub-domain. However, a large diagram can be intimidating to people who are not familiar with that domain. It increases cognitive load and the initial time to understand what’s really relevant. Problem specific diagrams come to the rescue! It is easier to communicate your point by choosing a narrow area of focus with only a few boxes or arrows. As a side benefit, there will be more space to add colour coding or multiple alternative proposals for the same problem area.

Tip #8 Right tool for the right job

There are three main types of diagramming tools. Offline tools such as draw.io or Gliffy are fairly quick to master. Collaboration tools such as Miro allows multiple people to work on a single board and get engaged with the problem. Finally, generators such as PlantUML or Structurizr are great for version controlling your diagrams together with your code. That’s especially helpful if you need strict controls over your diagrams or need to know their history. Some people prefer generators so they can work with a DSL rather than drawing shapes and that’s totally fine too.

Tip #9 There is no such thing as too much visualisation

A good diagram is almost always better than just talking about a problem. Most discussions deserve some sort of visualisation to help align everyone in the room so don’t wait for the perfect opportunity to share your diagrams. Use them generously even when everyone is confident in what they are talking about and offer to create a visualisation if no one else has.

These are just some of the principles I use in my day to day work. Please leave a comment if you find any of these tips useful or have additional suggestions to add!