7 More Common Mistakes in Architecture Diagrams

System architecture diagrams are essential tools for documenting complex systems. However, common mistakes in these diagrams can lead to confusion, misinterpretation, and frustration for viewers. Here’s a rundown of seven (more!) common mistakes to avoid.

This is a follow-up to the original 7 Common Mistakes in Architecture Diagrams.

Mistake #1: Not including resource names

Poorly labeled resources (the entities between the lines) is a common problem in system diagramming. Each resource in the diagram has an icon labeled with its type but not its name. While the resource type is certainly valuable, one is not a substitute for the other:

• Types describe what kind of thing a resource is. Types can include concrete items such as database tables or VM instances, or abstract items such as services.
• Names disambiguate resources from other resources of the same type. Descriptive names can also reveal the resource’s role or purpose.

When space allows, viewers are best off knowing both the name and type of a resource. This can be as simple as adding a type suffix to a resource name (e.g. Orders Table, Results Bucket).

#2 Unconnected resources

Resources in a diagram should always be somehow connected to the other resources. Including resources that are disconnected from all others is a mistake. Diagrams exist to show relations between resources, so omitting those relations defeats the purpose of the diagram to begin with.

This issue often arises from trying to include too much information in a single diagram (usually a “master” diagram).

#3 Making a “master” diagram

“Master” diagrams attempt to show an entire system at once. They stem from a misguided desire to “see it all” in a single diagram. They are almost always a mistake because including too much information will overwhelm the viewer.

The solution is to break up such a diagram into multiple perspectives (points of view). Each perspective tells a cohesive story without interfering with the others.

#4 Conveyor belt syndrome

Behavioral diagrams aim to show specific interactions between resources. Conveyor belt syndrome occurs when authors over-simplify them by omitting the realities of round-trips and orchestrations, depicting the system as a simple assembly line where data flows neatly from one resource to the next.

The solution is to use sequence diagrams, which are tailor-made to show detailed back-and-forth interactions between resources.

#5 Meaningless animations

Diagrams with meaningless, distracting animations have proliferated on social networks. These exist exclusively for marketing purposes. Unless you are creating a diagram primarily for marketing, avoid unnecessary animations like moving arrows that indicate nothing more than the direction the arrow already points.

#6 Fan traps

Fan traps occur when relation information between resources is lost in intermediate resources. For example, specific communications are lost if they are collapsed in a shared message broker. This can be fixed by adding more specific resources (like topics) inside the intermediate resources to restore communication paths.

#7 Assuming AI can create quality diagrams from source code

While AI can assist in "whiteboarding," diagrams generated automatically from source code are often vague and contain hallucinations. These problems stem from a lack of training data and the inability to strategically choose what to include and omit. For now, detailed system diagramming is still primarily a human endeavour.