Diagrams

Drawing in text

A lot of what I write is about systems, and systems want pictures — a flow, a sequence, an architecture with boxes and arrows.

The usual options are both bad. Drawing them in a design tool produces a beautiful image that is impossible to edit six months later and impossible to diff at all. Describing them in prose produces three paragraphs where a diagram would have taken four lines.

So diagrams are written as text inside the article, in a fenced block, using a diagram-description syntax. A flowchart is a list of nodes and the arrows between them. A sequence diagram is a list of who says what to whom.

That keeps a diagram in the same file as the prose it belongs to, versioned with it, diffable line by line, and editable by typing.

Rendered ahead of time, not in the reader’s browser

The usual way to put these on a page is to ship the rendering library and let each reader’s browser draw the diagram on arrival.

I do not do that, for three reasons.

Weight. The rendering library is substantially larger than most of my articles. Sending it to every reader so that some of them can see one diagram is a poor trade.

Stability. A diagram rendered in the browser appears a moment after the text does, and shifts the layout when it lands.

Failure. If the library fails to load, the reader gets a block of diagram source code where a picture should be.

Instead, diagrams are rendered at build time. The build finds every diagram block across the content, renders each to a vector image, and the page ships the finished picture. Readers download an image. No library, no layout shift, and nothing to fail on arrival.

Because the output is vector, it stays sharp at any zoom and it inherits the page’s own colours in both themes rather than being a light-mode picture sitting awkwardly on a dark page.

What this costs

Two things, and they are worth stating plainly.

The build got slower, because rendering diagrams is real work. It happens once per build rather than once per reader, which is the right place for it, but the build is where the cost lands.

And a diagram cannot be written that depends on knowing the reader — no interactivity, no data fetched at view time. For architecture diagrams in technical writing, that has never once been a limitation.

The rule underneath

This is the same trade the whole system makes, showing up in another module: do expensive work once, at build time, on my machine, so the reader’s browser does as little as possible.

The same reasoning is why decks ship as images rather than as re-flowed HTML, why images are measured on upload rather than on render, and why the front end is a renderer rather than an application. Each one moves work away from the reader and towards the build.