Skip to content
Software Architecture Guide

Self-Invented Notation Drawback

Explanation

Section titled “Explanation”

Many architecture diagrams are drawn as free-style boxes and lines. The author picks colors, shapes and line styles as they go. No one has defined what these symbols mean.

What goes wrong

  • The notation is not explained, or it is used inconsistently. Colors, shapes, line styles and element sizes may all be affected.
  • The purpose and meaning of elements stay ambiguous. A reader cannot interpret the diagram without the author’s help.
  • Diagrams drift as a system changes. Research on deployment diagrams reports that diagrams commonly become ambiguous or inconsistent as the system progresses.

Why teams end up here

Free sketching without structure tends to produce a confusing result. Many teams dropped UML (see Unified Modeling Language (UML)) in favor of much simpler boxes and lines. That choice trades precision for speed and ease.

Mitigations

  • Add a legend (also called a key) to every diagram. It should explain shapes, colors, border styles, line types and arrow heads.
  • Use a notation that others already know, such as UML, ArchiMate or SysML. Even then, keep the legend, because readers may not know that notation.
  • The C4 model (see C4 Model) prescribes no particular notation. It still requires a key on every diagram.
  • A design practice repository describes notations as ranging from ad hoc and informal to full-fledged. It says a non-standard notation needs a legend.

Example

Section titled “Example”

A team draws a diagram with blue boxes, green boxes, a dashed arrow and a solid arrow. The author means blue as “built by us” and dashed as “asynchronous call”. A new colleague reads blue as “database” and dashed as “optional”. Nothing on the page settles who is right. Adding a small legend that lists each color and line style removes the guesswork.

Trade-offs

Section titled “Trade-offs”

Free-style boxes and lines are quick to sketch and flexible. The cost is ambiguity: without structure the result can be confusing, and readers need the author to explain it. A legend adds a little effort per diagram but makes the diagram readable on its own. A known notation adds learning effort, and teams have dropped UML for simpler diagrams for that reason. Either way, the legend stays.

Checks

Section titled “Checks”
  • Every diagram carries a legend or key.
  • The legend explains shapes, colors, border styles, line types and arrow heads used in the diagram.
  • Any non-standard notation is accompanied by a legend.
  • Colors, shapes and line styles are used consistently across diagrams.
Section titled “Related”

Sources

Section titled “Sources”