SA-201c · Module 2

Diagram Design Principles

3 min read

A diagram that requires a legend longer than the diagram itself has failed. A diagram that requires a ten-minute verbal explanation to understand has failed. A diagram that looks beautiful and communicates nothing has failed. Architecture diagrams succeed when the reader can understand the system without additional explanation. That is the design standard. Everything else is aesthetic preference.

Do This

  • Label every box with both the name and the technology — "Order Service (Node.js)" not just "Order Service"
  • Label every arrow with the protocol and the data direction — "REST / JSON" not just a line
  • Use consistent visual language — databases always use the same shape, external systems always use the same border
  • Limit each diagram to 7 plus or minus 2 elements — beyond that, zoom into a sub-diagram

Avoid This

  • Draw diagrams with unlabeled arrows — the reader should not have to guess what flows between components
  • Mix abstraction levels in a single diagram — do not show API endpoints alongside system context
  • Use color for decoration — use color for information: red for external, blue for internal, green for data stores
  • Create diagrams so large they require scrolling — if it does not fit on a single screen, split it into levels

I measure diagram quality by mean time to explain. If I hand the diagram to a new team member and they can describe the system in under five minutes without my help, the diagram works. If they need my explanation, the diagram has failed its purpose — which is to communicate independently. The diagram is documentation, not a presentation aid.