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: when a task runs through more than one interface, the page declares its tab strip once, the first thing under ## Prerequisites, and each task carries a block of the same store with panels only, which renders that strip above its panels. Console first, one complete procedure per panel, and every panel opens with the interface’s name as a heading one level below its section.
• 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 branch through the page’s one strip, Console panel first — never sequential sections per interface, and never a strip per task.
• 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.
• Hold the values of the use cases a section serves. A use case explains a design and keeps its values off its page. The guide section that applies part of that design ends with a line naming the use case, In the [<use case>](/path/) use case, this section takes these values:, then a Setting | Value table and the outcome. When the section’s own example already uses those values, the line says so and no table follows. The confirm section ends with the use case’s expected results, under In the [<use case>](/path/) use case, expect:.

Examples

This excerpt shows the scope sentence, the prerequisites that carry the strip, 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