pedagogy

Pedagogy

The best writing instructions in this plugin were vendored with the tutorial agent, and then fenced off where almost nothing could reach them. In the last full run, 3 pages of 67 were doc_type: tutorial. The other 64 got none of it.

That was the wrong boundary. Teaching is not a genre of page. It is what any page owes a reader who has not used the product before, and that reader is on the how-to and the troubleshooting page too.

So these rules apply to every page whose audience is user, whatever its doc_type, and to operator pages wherever the operator is new to the product rather than new to terminals.

---

The four that matter

1. Say what the reader will end up with, first

Not what the page covers. What they will have when they close it.

• Weak: "This page covers the deployment wizard."
• Real: "By the end of this you will have one cluster running, and you will know which screen tells you it is ready."

For a tutorial doctype.py checks the literal "By the end of this tutorial you will be able to" because Good Docs is emphatic about it. On other types the wording is free and the obligation is not: the first paragraph tells the reader whether this page is for them.

2. Everything they need, before step one

A reader who reaches step 4 and finds they needed credentials has been failed, and they have been failed in a specific way: they now distrust the rest of the page.

State the lot up front: access, accounts, a thing installed, a decision already made. If nothing is needed, say that too. "You do not need an account for this" is a real sentence that saves a real reader a real detour.

3. A concept is introduced before it is used

The single most common way documentation assumes knowledge of the product it is documenting. A term appears on page one as though the reader has already met it, because the writer met it in the source an hour earlier.

• Expand an acronym the first time. Once. doctype.py checks this part.
• Introduce a product word the first time it carries weight, in one clause, not a paragraph.
• A term needing more than a clause belongs in the glossary, and the page links it.
• A whole concept needing to be settled before the task makes sense belongs on an explanation page, and the task page links that rather than teaching it inline.