​

How-to template

Use this template for a how-to guide: a goal-oriented page that helps a competent reader do one specific thing. This is the How-to quadrant in dev-doc-types. A how-to is not a tutorial. The reader already knows what they want — give them the steps, not a lesson. Do not explain what the feature is; link to a concept page for the “why”. Troubleshooting is a how-to. Per the Diataxis model and the convention used by Stripe and other API docs, there is no standalone troubleshooting page type. A “fix this error” page is a how-to with a diagnostic sequence; the error catalog itself is a reference page. Use the error-handling variant below.

​

When to use

• A single task: “Manage your inbox”, “Rotate an access token”, “Filter messages”
• Resolving a specific error: “Resolve a 401 Unauthorized”, “Handle rate limit errors”

​

Always apply

Apply all Foundational skills as you write — writing standards, accessibility, formatting, code examples, terminology. See SKILLS-INDEX.

​

Template location

assets/template-how-to.mdx — structure and placeholders only. Includes the error-handling variant.

---

​

Required sections (in order)

​

Writing the steps

• One action per step. Lead with the verb.
• Each API or SDK action gets a runnable <CodeGroup> (cURL → TypeScript → Python).
• State the goal once at the top; do not re-explain the feature mid-page.
• Move alternatives into an <AccordionGroup> so the main path stays linear.

​

Writing the verify step

• Give a concrete, runnable check (“Call GET /inboxes/$INBOX_ID and confirm status is active.”).
• Show the expected response so the reader knows what success looks like.

​

Naming

• Title is a verb phrase: “Manage your inbox”, “Rotate an access token”.
• For error pages, name the outcome: “Resolve a 401 Unauthorized error” — not “401 errors” (that noun phrase is a reference page).

---

​

Error-handling variant

Use this when the goal is to fix or handle a specific error.

• Replace ## Verify the result with ## When to contact support (and what to include in the report).
• Structure the body as a diagnostic sequence, not a symptom/cause/fix accordion list (that is a support-center pattern). Check A, then B, then C, in order of likelihood.
• Link to the error reference for the code’s canonical meaning, and link back from the reference to this how-to. This bi-directional link is the Stripe pattern.
• Keep the error code’s factual definition (status, meaning, retry-safe?) in the reference page — do not duplicate the catalog here.

​

Frontmatter

Set only title and description (see formatting-guidelines). List prerequisites in the ## Before you begin body section, not in frontmatter.

​

Before you finish

Register the page in docs.json and update llms.txt (contribute-docs), then run review-before-done.