More common mistakes to avoid when creating system architecture diagrams

Summary

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. 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 Here is a simple one: resources in a diagram should always be somehow connected to the other resources. Including resources that are disconnected from all others is a mistake. Amazon Route 53, on the right, is disconnected from every other resource. Source: amazon.com. In the diagram above from this article, Amazon Route 53 (on the right) is unconnected to the other resources. Its role in the system is completely unclear. Diagrams like this exist to show relations between resource...