How-to guides

Purpose

A how-to guide takes a reader who has a problem to a solved problem. The reader already knows what they want. The page removes the obstacles between them and the result; it does not teach.

When to use

• The reader arrived with a specific task and a real situation.
• Do not use a how-to for a reader who is learning the product: that page is a tutorial.
• A how-to whose task is a fix is a troubleshooting page.
• When in doubt, Choose a content type has the router.

Register

Procedural: 20 words per sentence, one instruction per step, imperative and active. Tone: directive, plain, efficient. Sentence structure holds the rules.

Structure

Required components

• Scope sentence: the opening states, in one sentence, what the page lets the reader do and from where. Never In this guide.
• Prerequisites: a ## Prerequisites section when the page has any, bulleted; each item is a link or a one-line command. A single prerequisite is a sentence, not a list.
• Task sections: one ## per task, each an imperative verb phrase.
• Lead-in: directly before each procedure, one sentence ending in a colon, such as To create the bucket:.
• Outcome sentence: every procedure ends by stating what the reader now has or sees.
• Next steps: a closing ## Next steps section, a DocCardGroup with one or two cards: the title, the link, and the reason as the card copy.

Optional components

• Tabs by interface: one <Tabs> block when a task runs through more than one interface, Console panel first, one complete procedure per panel.
• One aside holding the alternative path, when the task genuinely branches.

Template

Copy the template and replace each <placeholder>.

Separate the major sections of the page with a --- rule, and never place one directly after the frontmatter.

Rules

• Name the task in the title. A short imperative verb phrase: Create a bucket, Bypass origin cache. Not a gerund, not a question, not a How to ... prefix — the verb carries it. The prefix is retired on new and rewritten pages.
• Open with one scope sentence. State what the page lets the reader do and from where: You can create a bucket from Azion Console, the Azion CLI, or the API.
• One task per heading. A heading covering two tasks is two headings.
• Add information after every heading. A task section’s first sentence must add information its heading does not; the lead-in carries the section.
• Follow the step rules. Steps follow Procedures, and every procedure ends with its outcome sentence.
• Show the output after every command. The reader sees what success looks like before the next step depends on it. The rule is in Procedures.
• Branch where the task branches. Multi-interface tasks use one <Tabs> block, Console panel first — never sequential sections per interface.
• Do not teach. A sentence of context, then the steps. A paragraph of background belongs to a concept page; link it.
• Use one verb per action, on every mention across the page.
• Link the neighbors. Sibling how-tos and the product’s reference page, from the body or from ## Next steps.
• Send a goal that crosses products to a multi-product guide.
• Link out for third-party products. Name the vendor’s step; do not document their interface.

Examples

This excerpt shows the scope sentence, the prerequisites, and the Console panel of the first task:

• Create request and response rules: two tasks on one page, each a named procedure with numbered imperative steps.

Related