handbook-page

Handbook Page Skill

The handbook page is the highest-leverage document in team life: written once, it answers a question forever — but only if it's written answer-shaped. Most wiki pages are essay-shaped (history, context, philosophy, and eventually, maybe, the steps), while their readers arrive task-shaped ("how do I request access?"). The working page leads with the task, keeps context below the fold, carries the [doc-versioning-discipline](../doc-versioning-discipline/SKILL.md) header (owner, status, last-reviewed), includes one worked example — and then gets used: every repeat question gets answered with the link, because a handbook nobody points to is a diary.

What This Skill Produces

• The page — task-first structure: the answer/steps up top, the context and edge cases below
• The header block — owner, status, last-reviewed — the trust signals
• The worked example — one realistic walkthrough, because examples teach what steps can't
• The pointer habit — the answer-with-the-link move that makes the page pay for itself

Required Inputs

Ask for these if not provided:

• The repeated question — the actual thing people keep asking (verbatim asks beat topic descriptions — the [faq-builder](../faq-builder/SKILL.md) mining logic); pages written for imagined questions join the unread
• The answer, from the explainer — the current oral version, including the caveats and the "oh but if it's a contractor it's different" branches that live only in the explainer's head
• The audience floor — who arrives at this page and what they already know; the page assumes the floor and links the rest
• Where the handbook lives — and the naming/finding conventions there, so the page is discoverable by the words askers use

Framework: The Page Rules

1. Answer-shaped, not essay-shaped: the reader's task is satisfied in the first screen — the steps, the link, the form, the decision table. History and rationale live below under "Background," read by the curious minority. The test: the modal reader leaves within ninety seconds, satisfied.
2. Steps at do-this grain with branches explicit: the oral version's "oh, unless…" branches become visible forks ([runbook-writer](../runbook-writer/SKILL.md) grain for anything procedural) — the page must beat asking-a-human, and humans handle branches; pages that don't send readers back to the human.
3. The worked example is half the teaching: one realistic case walked end-to-end ("requesting prod access for a new analyst: …") — readers pattern-match from examples faster than they parse instructions, and the example disambiguates everything the steps left abstract.
4. The header makes it trustworthy: owner (who answers when the page is wrong), status, last-reviewed — without these, readers who've been burned by stale wikis re-ask the human anyway, and the page's ROI dies. The owner's review is 5 minutes on the heartbeat cadence.
5. The pointer habit is the payoff loop: from publication day, every repeat ask gets "here you go: [link] — tell me if anything's unclear" — which (a) delivers the answer, (b) trains the link-first reflex, and (c) field-tests the page (every "the page didn't cover my case" is an edit, same day). Explaining orally after the page exists is paying twice for the same knowledge.

Output Format

[Page title = the question, in the asker's words]

Owner: [name] · Status: active · Last reviewed: [date]

The Answer

[Steps/decision table/link — first screen, task-complete]

Worked Example

[One realistic end-to-end case]

Edge Cases & Branches

[The "unless…" forks, explicit]

Background (for the curious)

[Why it works this way · history · related pages]

Quality Checks

• [ ] The first screen completes the modal reader's task
• [ ] Branches from the oral version are visible forks, not omissions
• [ ] The worked example is realistic and end-to-end
• [ ] The header carries owner, status, and a real review date
• [ ] The pointer habit started on publication day — the next ask got the link

Anti-Patterns

• [ ] Do not open with history — the reader is mid-task; context is the appendix
• [ ] Do not write the ideal process — document the real one, or the page and reality diverge and both lose trust
• [ ] Do not skip the example to save time — it's the half of the page that actually teaches
• [ ] Do not publish ownerless — orphan pages rot into the stale wiki that taught readers to re-ask humans
• [ ] Do not keep explaining orally — every post-page explanation is a vote against your own infrastructure