Write an annotated walkthrough

Annotated walkthrough

One subject (a diagram, a screenshot, a piece of code) with numbered notes pointing at its parts. The reader sees the whole first, then goes note by note. Unlike scrollytelling, the subject does not change: the notes move around on it. Start with the explainer skill if you have not chosen a format yet. Setup and publishing are in the Bloggo skill.

When it fits

• Explaining a system architecture, a user interface, a form, a chart, a function, a config file or a data model.
• The parts matter and the reader may want to study them in any order.
• Not for a story over time (use scrollytelling) and not for one tiny object with two parts (a caption does that).

Structure to pair it with

• How it works: the notes follow the path through the thing, in order of use.
• Layered: one sentence for the whole above the block, the notes for the parts, deeper detail below the block.
• Answer first: say what the thing is for in the opening paragraph, then the notes.
• Add page furniture for definitions of terms the notes use. Code subjects follow the rules in math-and-code-blocks.

Syntax

A walkthrough block holds one subject followed by one numbered list. Each list item starts with a target in braces that says where on the subject it points.

::: walkthrough

![Checkout page of the shop, with cart on the left and payment on the right](/media/01J.../checkout.png)

1. {at="12% 20%"} The cart lists what the buyer is paying for. Changing a quantity updates the total at once.
2. {at="70% 35%"} The payment form takes a card number. Nothing here is sent to our server.
3. {at="70% 80%"} The pay button stays grey until every field is valid.

:::

Targets by subject type (a diagram is an image, and an SVG works too):

• Image: at="x% y%", the point from the top-left corner, each from 0 to 100. Optional box="x% y% w% h%" to outline an area instead of a point.
• Code block (fenced, with a language): lines="3-5" or lines="7". The line numbers are those of the block as written.

Rules: exactly one subject per block, and the list must be numbered with 1., 2. and so on, with every item carrying a target. Three to eight items is the right size; more than ten means two walkthroughs. Unknown options or a missing target make the block fall back to a plain figure with a numbered list.

How to write one

1. State what the subject is and what the reader will understand after the notes, in one or two sentences above the block.
2. Look at the subject as a reader would and find the five or so parts that matter. Skip the obvious ones.
3. Order the notes by the path a reader's attention should take: usually the path of use or of data, not left to right on the picture.
4. Write each note in 15 to 50 words: what the part is, then what it does or why it is there. Do not just restate the label.
5. For images, check the coordinates by previewing: a pin should sit on the part, not next to it.
6. Below the block, say what to take away, or what to try next.

Checks

• Each note makes sense alone. A reader may jump to note 4.
• The numbers in the list are the only order: do not write "the next note" or "as above".
• Alt text describes the subject as a whole; the notes describe the parts. Do not repeat one in the other.
• Read the post with the block removed and only the numbered list left. It must still be understandable as a list.

Mistakes

• Annotating everything. A pin on every pixel hides which parts matter.
• Screenshots too small to read on a phone. Crop to the relevant area, or split it into two walkthroughs.
• Code walkthroughs that read the code aloud ("this line declares a variable"). Say why it is there.
• Notes that explain things the subject does not show. Move that to the text around the block.