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. — 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 for what converts cleanly and what does not.

Diagram types

The recommendation per diagram type.

Examples

Working source in both styles.

Guides

How to drive each editor.

Write what changes. Draw what matters.