There’s a number from September that’s changed how I write a how-to. On the estate’s docs sites, pages that turned up at positions four to ten in a search were clicked 0.31% of the time.

Three clicks in a thousand appearances! Whatever those pages are for, I suspect it isn’t being read by the people doing the searching.

Who’s reading, then

Something is reading them, though, and that very week the blog’s weekly report had started counting it. Assistants fetch a page when someone asks them a question, read what they find, answer, and move on. For a lot of documentation that fetch is the visit now, and the person who asked quite possibly never sees the page at all.

So which pages got fetched most? I’d have liked it to be the best-written ones, or the most complete… it was the pages whose first screen was a quotable command, something an assistant could lift out whole and hand straight back.

That’s a problem for a how-to written the way I’d been writing them (which is to say, the way most of us were taught). You open with what the tool is and why you’d want it, then the prerequisites, then a caveat or two, and somewhere below that is the command. A person skims past all of it and finds the block. An assistant reads the first screen, finds a paragraph of preamble, and quotes the preamble.

Three projects one morning

So early one morning I went at the docs of three projects: the credential guides for keryx, the reference pages for ffmpeg-wasi, and afmpeg’s guide to remuxing a file without re-encoding it.

That last one is the clearest before and after. It used to open like this:

Most container changes don’t need a transcode. Moving mp4 → mkv, or joining segments that already share a codec, is a stream copy: read the demuxed packets, optionally fix their bitstream framing, and mux them straight back out, with no decode and no encode…

All true, and a good paragraph (I wrote it, I’m allowed to say so), and 132 words of it before the first line of code. It now opens with the command most readers already know, and then the job that does the same thing:

What ffmpeg -i in.mp4 -c copy out.mkv does on the command line (-c:v copy -c:a copy: copy the streams, change only the container), as an afmpeg job:

cmd := afmpeg.Command{
    Inputs: []afmpeg.Input{{Path: "in.mp4"}},
    Outputs: []afmpeg.Output{{
        Path:       "out.mkv",
        Map:        []string{"0:v", "0:a"},
        VideoCodec: afmpeg.CodecCopy,
        AudioCodec: afmpeg.CodecCopy,
    }},
}
_, err := rt.RunJob(ctx, fs, cmd)

Twenty-seven words, then the code. The paragraph about stream copies is still there, word for word, directly underneath it. It just moved down the page.

Having done it on three sites I wanted it written down somewhere other than my memory (not something to lean on at that hour of the morning), so it went into the estate’s Diátaxis skill, the guidance any agent or person writing docs here reads first. The last of the three was committed just before seven, and the rule was in the skill a quarter of an hour later.

The rule

It’s short.

A how-to opens with whatever does the job, directly under the heading: the command, the config block, the API call, ten lines at most, and one sentence saying what it does. A reference page opens with whatever a person came to look up, the table or the field list or the exit codes.

Whatever the page used to say first goes underneath that block, and the rest stays as it was. More often than not the page itself was fine… it was just in the wrong order.

The front matter matters too. The description is the sentence an assistant quotes when it’s deciding whether a page answers the question, so write it as that sentence and not as a label. And when a page catches searches meant for something next door (a plain ffmpeg exit code landing on the WASM engine’s error page, say), answer that searcher in a short callout and say whose page they’ve landed on. Answer a mis-hit well and it gets quoted; ignore it and it’s a bounce, and they leave annoyed with you in particular.

You can check it from the shell

It needs no judgement to enforce, which I think is a big part of why it’ll stick. Count the words between the page’s title and its first code block or table:

awk '/^# /{h=1; next} h && /^(```|\|)/{print n+0; exit} h{n+=NF}' page.md

Under a hundred is answer-first, several hundred is a page that explains before it helps. The remux guide went from 132 to 27. It’s a number you can put in a merge request, before and after, and it takes most of the argument out of review.

Except tutorials

In one place this would do real damage, so the rule is scoped to two of Diátaxis’s four kinds of page.

A tutorial shouldn’t open with the finished command. Its reader has chosen to spend twenty minutes learning something, and the setup, the order of the steps and the small wins along the way are what they came for. Putting the finished command at the top tells them the destination and takes away the reason to walk there. Anyone who only wanted the command was probably after a how-to in the first place.

So how-to and reference pages get written for a reader who might be a machine and is probably in a hurry. Tutorials and explanation stay written for someone who’s put the kettle on and sat down to learn. Diátaxis has always said different pages serve different readers; the only new bit is that one of those readers is now a piece of software with a fetch budget, and it stops reading a good deal sooner than the rest of us.