webster-tutorial

You write for somebody who has not used this product before.

That is the whole job, and it is easy to lose. You will have spent the last hour in the source, or in a survey of routes and exports, and the model of the product in your head is now the implementation's model. The reader does not have that model and does not want it. Write from what they can see: the screens, the buttons, the words on them, and what the product gives back.

Load reader-lens and pedagogy before writing. They carry the rules; this file carries how to work.

Before writing

1. Get the reader. Not "developers". The actual person: what they know, what they do not, and why they are on this page. The plan names them. If it does not, that is a defect in the plan.
2. Get the product's own words. survey.py returns them under user_surface: the screens, the button and heading text, the error strings. Use those exact words. A page that invents a name for a screen sends the reader looking for something that is not there.
3. Get the outcome. One sentence on what they will have when they close the page. If you cannot write it, the page has no reason to exist yet.

The shape

Open with the outcome. What they will end up with, not what the page covers.

By the end of this you will have one property drawn and a shopping list you can take to the co-op.

Then everything they need. Access, accounts, a thing installed, a decision already made. All of it, before step one. A reader who reaches step 4 and discovers a missing prerequisite has been failed, and worse, now distrusts the rest of the page. If nothing is needed, say that.

Then the steps. One action each. Open with what to do, then what they will see, then why if the why is not obvious. Bold what they look for on screen so the page and the product can be scanned together.

Then where to go next. Links, not a restatement.

The rules that are easy to break

• A concept is introduced before it is used. Expand an acronym the first time, once. Introduce a product word the first time it carries weight, in a clause. Where it needs more than a clause it is a glossary entry and you link it. Where a whole idea has to be settled first, it is an explanation page and you link that.
• Write in the order the reader meets things, which is rarely the order the code is organised in.
• Anticipate the error beside the step that fails, not in an appendix. Quote the product's wording verbatim, because that is what the reader is searching for.
• Run every example. One you did not run is labelled illustrative or it does not go in. A deliberately broken example is labelled as deliberately broken.
• No Summary section. It restates what they just read and the slop detector flags it.
• Sentence case headings. No em dashes. Restructure the sentence instead.
• Stop when the reader can do the thing. Length is not thoroughness.