7 Common Mistakes in Architecture Diagrams

When creating a technical architecure diagram, your goal is to give understanding to your audience. You want to truly inform them about your system, rather than merely make an impression. Mistakes made when creating diagrams can undermine this goal, however. Here are seven common mistakes to avoid when making your next technical architecture diagram.

Mistake #1: Making a theoretical diagram

First, a definition: theoretical (or abstract) architecture diagrams demonstrate how a solution might generally look and run. Concrete diagrams, by contrast, show a specific instance of an architecture that enables (or will enable) specific applications for specific users.

Creating theoretical diagrams isn’t always a mistake, of course. That said, you probably don’t want to be making theoretical architecture diagrams most of the time. A concrete diagram of your organization’s specific architecture is almost certainly more informative and more valuable than a theoretical architecture diagram. Why?

The reason is because theoretical architecture diagrams are ubiquitous. You can find theoretical diagrams of, for example, Kubernetes-based architectures everywhere online. If a new hire needs a general lesson on Kubernetes, those already exist. You don’t need to make another one.

Conversely, how many architecture diagrams exist that show your organization’s specific architecture? How many show the named resources, how they’re related, where they are running, and what applications they support? That’s the architecture diagram your new hire needs. Make that diagram instead.

#2: Mixing levels of abstraction

This is a sin borrowed directly from programming, though it is just as applicable to diagramming. The mistake is having an architecture diagram that mixes high-level resources and low-level resources.

In the diagram above, low-level resources (individual lambdas) are linked directly to a high-level resource (DynamoDB, the AWS service). Showing only that these lambdas use DynamoDB is unbalanced and not very informative. Much better is showing which functions use which tables in the database, since functions and tables exist at the same level of abstraction. With this change we’re doing a better job of informing the viewer:

Both high- and low-level diagrams have their place, of course. If you’d like to have both, makes sure to split them into two separate diagrams.

#3: Too many overlapping concerns

Busyness is a common problem in architecture diagrams. Diagram authors often have a lot to say, and not a lot of space to say it. One of the most common kinds of busyness is showing too many overlapping concerns at once.

The above example pretty much tells the story. While its abstraction is consistent, this architecture diagram includes resources, a region, a VPC, auto-scaling groups, subnets, and availability zones. The diagram is about how data flows between resources (hence all the arrows, though see the next item), but because it is so jam-packed with all these other concerns, the message is not strong. The auto-scaling groups, in particular, are literally overlapping everything else.

Like with the previous problem (mixing levels of abstraction), the solution here is to split up a single, busy, diagram into multiple diagrams, each focused on one or two concerns at a time.

#4 Unlabeled arrows

This one is as straightforward as it is common: unlabeled arrows are almost always wrong. An unlabeled arrow tells the viewer that two resources are somehow related, but not exactly how. This is as clear a violation of “strive to truly inform” there is.

Unlabeled arrows can be OK if the exact nature of the relation can be inferred. One obvious example is a series of arrows with the same relation that are very close together; in this case omitting the repeating labels is a good thing (as it reduces visual noise). Unlabeled arrows are also fine when they overlap each other. In all other cases, though, if you have an arrow, it needs a label.

#5 Misleading composition

Every problem so far has fallen in to the category of an architecture diagram providing too much, too little, or irrelevant information. This mistake, misleading composition, is a problem of providing information that can outright mislead.

This is best explained by example. Can you spot the misleading composition in this AWS diagram? Hint: composition (boxes inside other boxes) is used to show what resources exist inside or run in other resources.

The composition of this diagram tells the viewer that the Drupal Instances run inside their respective subnets, which in turn run inside two availability zones (AZ1 and AZ2). This is all accurate; the problem is that the composition is also (erroneously) telling the viewer that the availability zones are running inside the VPC. AWS experts might know this is not the case, but novices might come away wrongly believing that availability zones are resources of a VPC.

One option is to simply omit the out-of-place resources (and potentially show them in another perspective). However, if we really want to show these resources in this perspective, it is viable to simply draw them differently. A dashed outline, for example, gives a clear indication that the composition of these elements are different than the others:

#6 Missing context

Another potential solution to the above is to eschew composition altogether and not provide context to any of your resources. I think this is a mistake; while you may know where your resources live, you cannot count on every viewer knowing.

Including one or two levels of composition (though not to the point of showing too many concerns, see #3) provides both organization and important contextual information to those who are new to your architecture:

#7 Missing accompanying explainer text

Finally, always remember that architecture diagrams can’t explain everything. In particular, though great at showing what, diagrams on their own are not good for explaining why. Include ample prose alongside your diagrams to both introduce your architecture and highlight critical design choices and why they were made.

Better still, if your tool allows for it, add a walkthrough to your diagram to explain what is happening (and why) at each step.

I hope this was helpful! Please reach out with your thoughts at billy@ilograph.com or @ilographs on Twitter. For more information about Ilograph diagrams, check out the Ilograph homepage or see an example diagram.