GoKawiilSystem 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. Consider the labels under the icons in this AWS diagram:
The resources in this diagram are labeled by type instead of by name. Source: amazon.com.
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. Types can be written out or represented as an icon.
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). Diagram icons/shapes typically indicate the type (as they do in the diagram above), so labeling a resource by name is especially preferable when an icon is present.
#2 Unconnected resources
... continue reading