Writing rules: How-to guides

How-to guides are goal-oriented. The reader is a competent user in the middle of real work with a specific goal; the guide is directions to that goal, not a lesson and not a manual.

The reader

• Already knows their way around the application's basics.
• Arrives with a goal formed in their own terms ("bill a contract early", "fix a failed device poll") and wants the shortest reliable route to it.
• Can adapt directions to their situation — they need guidance, not hand-holding.

Rules

• Title names the goal: "Configure…", "Recover from…" — a reader should recognise their own problem in it.
• Order the guide as a sequence of actions toward the goal. Keep every sentence pointed at the goal; cut anything that doesn't advance it.
• Assume competence: no teaching, no background, no re-explaining what the reader already knows to have this goal.
• Address real-world variation where it genuinely forks the path ("If the supplier uses OAuth… otherwise…"), but do not attempt completeness — usability beats coverage.
• Name the starting conditions (what must exist or be configured first).
• Link to reference topics for option details and to explanation topics for the reasoning behind the approach.

Avoid

• Conceptual explanation — a how-to that begins with "Understanding X" belongs in two other documents.
• Enumerating every option or edge case — that is reference material.
• Starting from absolute zero; that makes it a tutorial.

Quality check

Could a competent user with this exact goal follow the guide under pressure and get there without reading anything else?