practice

Diagram Notation Consistency

Using shapes, colours, line styles and arrow directions to mean the same thing across every diagram, and stating what they mean on the diagram itself.

Most architecture diagrams fail for the same avoidable reason: the reader does not know what the symbols mean, so they guess, and different readers guess differently.

The specific ambiguities that cause the most damage:

Arrow direction. Does the arrow mean "calls", "sends data to", or "depends on"? These frequently point in opposite directions for the same relationship, and a diagram that mixes them is worse than one with no arrows.

Boxes at different abstraction levels. A business capability, a microservice, a database table and a cloud region on one diagram is the single most common defect, and it makes the whole picture uninterpretable.

Colour without meaning. If colour is decorative, readers will infer significance anyway.

Undefined line styles — dashed for asynchronous, for optional, for planned, for network boundary, depending on who drew it.

The remedies are cheap: a legend on every diagram, even an obvious one; a small house convention for shapes, colours and line styles, published once; one abstraction level per diagram; and a title that states what question the diagram answers.

And date every diagram, with a clear label distinguishing current from intended. An aspirational diagram presented as fact misleads exactly the people who most need it to be right.