Writing guides

A guide is something people rely on again and again: how to do something, or how something works. It is kept up to date and improved as practice changes, so it carries a status ("on trial", "current") rather than a date. If you are telling people once about what happened or what is proposed, write a briefing instead.

These are patterns that have worked, not rules; use judgment. The shared principles, how to sound like a person and how to make one with AI are in Writing for the team.

Guides live next to the work they describe, such as a repository's guides/ or docs/; list procedures in procedures. Two kinds come up most.

How-to guides: point, prompt, picture

Learned writing The weekly review (26 Oct 2026). AI drafts of how-to guides run long and explain the machinery; people need to get the point and get started. The first draft of that guide was three screens; the one that worked fits on one.

• The point in one line. What it does for you, not how it works.
• The way to start straight after. Usually a prompt to copy and paste, in a quote block.
• One picture of the steps. ASCII, at most 50 characters wide: who acts at each step (AI or you), where you step in, and where the results end up. For quick understanding this often does more than any amount of prose.
• Example answers, one line each, at the points where the reader has to say something.
• A few "good to know" bullets, then links. Internals, file formats and rationale go in the skill or the project record.
• A useful check: can a reader start within ten seconds of opening it? If not, look for what to cut.

Adapt it: a guide with no single starting prompt, or whose steps are obvious, may need no picture.

 # <Name>

 <One line: what it does for you.>

 **To run it,** paste:
 > <prompt>

 <picture: steps, who acts, where results go>

 <1–2 example answers at the stops>

 ## Good to know
 - <3–4 bullets>

 More: <skill>, <project record>

Guides that explain concepts

Learned writing Post-its and filing cabinets (15 Oct 2026). For a guide whose job is to build a mental model:

• Map the concepts before the skeleton. List each concept, what it depends on, and the order the source introduced them. Try two or three orders through that map, then choose one linear path and say why.
• One new idea per step, each with its own picture. Build up from the smallest, most concrete thing (a sheet of paper) to the larger ones. Grow one scene rather than drawing a new world each time.
• Metaphor first, tools last. Work the analogy all the way through before mapping it to real systems. Keep anything specific to us in its own final part, so the rest works for any reader.
• No front-loaded summary. Open with one line and a map, not a TL;DR that explains everything at once. Mark side points as extras.
• Make the map a picture of the argument, not a table of contents. Number the steps, give each a gist of a few words and a small icon, show the flow with arrows, mark the key idea, and show branches and checkpoints. Keep it tall and narrow so it doesn't wrap.
• Pick a running example that is obviously one project. A summer retreat is clearly one piece of work with an end; "the autumn series" of a podcast left readers unsure what the project was.
• In pictures of documents, write one point per line (what, why, who leads, done by), not a wrapped sentence.

Keeping a guide current

• Mark what is on trial or still open, and say who decides.
• When practice changes, change the guide in place and commit; don't write a new one alongside.
• If a briefing announced a change, the guide is where it lives afterwards.