# Text or visual diagrams

This is the first real decision you make, and the one people most often get wrong. Neither answer is better; they fail in different ways.

---

## The trade-off

![The Excalidraw canvas with a hand drawn flowchart in which Step 1 leads to a decision that branches yes to Step 2 and no to Step 3, with a style panel open on the left.](https://help.gocapable.com/images/ca7ccc7f-2a17-42ab-bc6c-1e70faa7bc66.webp)

Drawing by hand gives you direct control over the position, colour and style of every shape, which is what writing source asks you to give up.

| **Written as text**              | **Drawn by hand**                              |                                             |
| -------------------------------- | ---------------------------------------------- | ------------------------------------------- |
| **Changes often**                | Ideal. Edit a line, the layout redraws itself. | Painful. Every change means nudging shapes. |
| **Layout carries meaning**       | Weak. You get the layout the engine chooses.   | Ideal. You place everything deliberately.   |
| **Reviewable in a pull request** | Yes, it diffs like code.                       | No, only the image changes.                 |
| **Non-technical contributors**   | They will not edit the source.                 | Anyone can drag a box.                      |
| **Large and dense**              | Degrades. Auto-layout gives up.                | Scales, with effort.                        |

---

## A rule of thumb

📝

**Write it if the diagram is generated from something that changes.** Draw it if the diagram is the thing itself. A sequence of API calls should be written. A datacentre floor plan should be drawn.

---

## You are not locked in

Several formats convert between each other, and the original source is kept when they do. See [Reference](https://help.gocapable.com/diagrams/reference.html) for what converts cleanly and what does not.

---

## Related

[Diagram typesThe recommendation per diagram type.](https://help.gocapable.com/diagrams/diagram-types.html)

[ExamplesWorking source in both styles.](https://help.gocapable.com/diagrams/examples.html)

[GuidesHow to drive each editor.](https://help.gocapable.com/diagrams/guides.html)

---

_Write what changes. Draw what matters._