# Should you draw it?

> Decide whether a picture beats a sentence or a table, then pick where the picture should live by who touches it next.

Module: Diagrams · Level: beginner · 6 min · https://school.agents.org.in/visual/diagrams/should-you-draw-it

Here is the same idea said three ways. Pick a piece of content, then flip between a sentence, a table and a picture. Only one of them is the best fit each time, and it is not always the picture.

*[Interactive demo: Three plans want a table. A checkout with a retry loop wants a picture. One relationship wants a sentence.]*

A diagram is the most expensive way to say something. It costs layout, labels, a legend and a review. And a wrong one teaches the wrong structure faster than a paragraph ever could, because people trust pictures.

So the first question is never "which kind of diagram?". It is **does a reader learn more from a picture than from a paragraph or a table?**

## Picture, table or sentence

Most content falls into one of a few shapes. Each shape has a format that suits it.

| The content is… | Use |
|---|---|
| A list of things, or attributes side by side | a table or bullets |
| One relationship ("the API calls the queue") | the sentence |
| A before and after where only attributes change | a table |
| Flow, nesting, order in time, dependency, position on two axes | a diagram |
| Live numbers inside your product | a chart component, not a figure |

The test is simple. If a three-column table carries the same meaning, the table wins. If a sentence does, the sentence wins.

> **In plain words.** A diagram earns its place when the **shape** of the idea is the point: something that loops, branches, nests, or happens in order. If you could read it out as a list without losing anything, it is a list.

The trap is "before and after". If a redesign only changes attributes (a new price, a new name), that is a table. If it changes the **topology**, meaning which thing connects to which, that is a diagram.

## Who touches it next?

Once you know a picture helps, the next question decides where it lives. A picture has a surface (Where a picture lives: a finished figure, an editable canvas, a Mermaid block in the docs, or FigJam. You pick it by who touches the picture next), and you choose it by asking who will touch it next.

  **Step: Readers only read it.** A doc, a blog post, a README, a deck, a pull request. Make a finished editorial figure (A finished diagram made for people to read, in a doc, post, README or deck. It is polished once and not edited by hand afterwards): one HTML file with the drawing inside it as SVG. Cathryn Lavery's diagram-design skill draws these.

  **Step: A team keeps moving boxes.** Planning, whiteboarding, reviewing in comments. Use an editable canvas (An endless editable whiteboard, like tldraw or FigJam, where a team keeps moving boxes and arrows around after the first draft) like tldraw, where arrows stay attached when someone drags a box.

  **Step: It lives beside the code.** A picture that changes when the code changes. Write it as a Mermaid (A way to write a diagram as short text (A --> B) that a docs site turns into a picture. Good for structure kept next to code; its automatic layout looks generated in a finished figure) block in the Markdown, versioned with the text it explains.

  **Step: The team lives in Figma.** Use FigJam. Meet people where they already work.

One picture, one surface. When a canvas grows up into a published figure, redraw it from its structure. Never paste a screenshot of a whiteboard into a doc and call it the figure.

*("Make a diagram" from someone who edits it tomorrow is a canvas job.)*

## Try the whole decision

Here is that flow as three questions. Answer them for something you have been meaning to diagram.

*[Interactive demo: What it is, who touches it next and how big it is. The answer is a format and a surface, not a style.]*

Notice that three of the four first answers end in "don't draw it". That is the honest ratio. Most "can you diagram this?" requests are tables wearing a costume.

## The budget

A single figure holds about **9 boxes, 12 arrows and 2 accent colors**. That is the diagram budget (The most one figure should hold: about 9 boxes, 12 arrows and 2 accent colors. Past that, split it into an overview and a detail). Past it, the figure is really two figures: an overview that shows the big parts, and a detail that zooms into one of them.

diagram-design aims for a density of about 4 out of 10: complete enough to be correct, sparse enough that nobody needs a guide to read it. A canvas has no hard budget, but if a board needs a legend to find your way around, it needs frames (labelled groups) instead.

  **Before (avoid):**

One architecture figure with 22 boxes, 31 arrows and five highlight colors. Every part is there; nobody can find the path a request takes.

  **After (do this):**

An overview with 6 boxes (the main services), plus one detail figure for the payments service with its 8 parts. Each fits the budget and has one thing to say.

## Ask your agent the right way

Agents love to say yes to "diagram this". The skill makes them ask the cheap questions first. You can too, in the prompt.

**Decide before drawing (paste into your agent):**

```text
Before you draw anything, decide whether this should be a sentence, a table or a diagram, and say why in one line.
If it is a diagram, ask me who will touch it next (readers, a team editing it, the code, or Figma) and pick the surface from that.
Keep one figure under 9 nodes, 12 connectors and 2 accent colors; if it needs more, propose an overview and a detail instead.
```

Two gotchas to remember. A chart inside a live product is not a figure at all: it is a component with loading, empty and error states. And if the request does not say who edits the picture next, that is a question to ask, not a guess to make.

**Check yourself:** A teammate asks for a diagram comparing your three pricing plans on seats, storage and support. What should you make?

- [ ] A flowchart from Free to Pro to Team
- [x] A table with a column per plan
- [ ] An editable tldraw board
- [ ] Three boxes with the attributes inside, joined by arrows

*Why:* Attributes compared side by side are a table's job. There is no flow between the plans, so arrows would invent a relationship that isn't there.

## In the skill

- https://school.agents.org.in/skill/diagram/MOC-diagram.md
- https://school.agents.org.in/skill/diagram/diagram-decision.md