Diagram rules

A diagram is a set of claims drawn instead of written. Every box and arrow makes a claim, so every one has to earn its place, the way a sentence does. The tool comes last: decide what the picture says first, then pick the notation the repository already uses.

Lessons here come from Cathryn Lavery's diagram-design and Riekelt's diagramming-processes (both MIT).

1. Whether to draw at all

Draw only when the reader's question is about shape: order, branching, containment, who talks to whom, what depends on what. Otherwise the plainer form wins:

If a three-column table says the same thing, use the table. A diagram of a straight line is a list wearing boxes.