Learning the notation

A diagram is a text file. You say where things go and what connects to what; the drawing is worked out from that and nothing else.

Every example below is a complete document. Copy any of them into the editor and you will get the drawing beside it.

Every example is a complete document — open the editor and paste one in. The full specification is Platen.

1. A first diagram

Put something in a cell. A1 is a column letter and a row number, the way a spreadsheet names a square, and it both names the thing and places it.

A1 "HELLO"

Nothing is inferred. There is no layout engine deciding where things ought to go — you decide, and the result is the same every time you draw it.

2. The grid

Columns run A, B, C across; rows run 1, 2, 3 down. Leave a gap and the gap stays: an empty column is space you asked for.

A1 "CLIENT"
C1 "SERVER"
E1 "DATABASE"

Flow reads left to right and tiers read top to bottom, so composition carries meaning. Two things in one column are two things at one stage.

3. Pictures

A bare word before the label draws a symbol. There are around 1,500 of them, and the common ones are named plainly.

A1 user "CUSTOMER"
C1 browser "WEB APP"
E1 database "ORDERS"

Every symbol takes the drawing's own ink, so a page reads as one hand rather than as a collection of logos.

4. One thing, several cells

A range spans. C1:E1 is one item occupying three columns — useful for a band of prose, or for something genuinely wider than its neighbours.

A1 user "CUSTOMER"
C1:E1 "A WIDE BLOCK OF EXPLANATORY TEXT ACROSS THREE COLUMNS"
A3 server "API"
C3:E3 database "THE STORE"

5. Naming things

C2 is a position, so moving something changes its name — and anything pointing at it has to change too. Give it an #id and the name stops depending on where it sits.

A1 user "CUSTOMER" #who
C1 server "API" #api
E1 database "ORDERS" #store

Move #api to another cell later and every line that mentions it still refers to the same thing. It is worth adding an id the moment something is referred to twice.

6. Connecting things

-> draws an arrow. <-> draws one with a head at both ends. A label in quotes rides on the line.

A1 user "CUSTOMER" #who
C1 server "API" #api
E1 database "ORDERS" #store

#who -> #api
#api -> #store "READS"
#api <-> #store "WRITES BACK"

You never route a line. Where it bends, where it crosses and where it breaks to show which line passes in front are all worked out for you.

7. Grouping

Square brackets draw a boundary around things. List what belongs inside; add a label, and a symbol if you want one on the label.

A1 user "CUSTOMER" #who
C1 server "API" #api
E1 database "ORDERS" #store

[#api, #store "PRIVATE NETWORK"]

#who -> #api
#api -> #store

Boundaries may nest, and they may also overlap without one containing the other — two networks that share a machine is a real thing to draw, so it is drawable.

8. Titling the sheet

Four keywords put text in the margins rather than in the grid: a title, an attribution, and notes in any of the four corners.

TITLE "ORDER INTAKE"
ATTRIBUTION "PLATFORM TEAM"
NOTE TL "DRAFT"
NOTE BR "REVIEWED 2026-08"

A1 user "CUSTOMER" #who
C1 server "API" #api
#who -> #api

The margins are part of the drawing, so nothing else has to repeat them.

9. A scannable corner

CODE puts a QR in a corner of the sheet. It encodes the diagram's own short link, so a printed copy or a slide carries a way back to the live version.

TITLE "ORDER INTAKE"
CODE BR

A1 user "CUSTOMER" #who
C1 server "API" #api
#who -> #api

The link is filled in when the diagram is drawn, so it is never something you type and never goes stale.

10. More than one grid

A page is a separate grid in the same document. Mark a cell with @ and it becomes a way in: on a published diagram, that cell is clickable.

PAGE main "SYSTEM"
A1 user "CUSTOMER" #who
C1 server "API" #api
E1 "PAYMENTS" @payments
#who -> #api
#api -> E1

PAGE payments "PAYMENTS"
A1 server "CHARGES" #charges
C1 database "LEDGER" #ledger
#charges -> #ledger

Nothing may cross between pages. A connection that leaves a page is a cell you place on both, which keeps each grid readable on its own.

11. Movement

A KEYFRAME starts a new frame, and everything after it is a change to the one before. Add something, re-place something, or HIDE it.

TITLE "SCALING OUT"

A1 user "CUSTOMER" #who
C1 server "API" #api
#who -> #api

KEYFRAME "UNDER LOAD" 1200ms
C2 server "API" #api2
#who -> #api2

KEYFRAME "STEADY" 1200ms
HIDE #api2

frame 0

frame 1

frame 2

Frames are a delta rather than a copy, so a three-frame document is not three documents.

12. Looking closer

ZOOM says which part of the drawing to look at. It holds until another one replaces it, so a sequence of frames can move around a diagram.

TITLE "WHERE THE WORK HAPPENS"
ZOOM #api PAD 1

A1 user "CUSTOMER" #who
C1 server "API" #api
E1 database "ORDERS" #store
#who -> #api
#api -> #store

Everything named stays visible when the move ends — a zoom frames things, it never crops them.