# 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](/en/documentation/style-guide/content/tutorials/).
- A how-to whose task is a fix is a [troubleshooting page](/en/documentation/style-guide/content/troubleshooting/).
- When in doubt, [Choose a content type](/en/documentation/style-guide/content/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](/en/documentation/style-guide/writing/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>`.

```mdx
import DocCardGroup from '@aziontech/webkit/doc-card-group'
import DocCard from '@aziontech/webkit/doc-card'

[One scope sentence: what the page lets the reader
do, and from where.]

## Prerequisites

- <A link or a one-line command per item>

---

## <Imperative verb phrase that names the task>

To <reach the result of the task>:

1. <One imperative instruction.>
2. <One imperative instruction.>

<The outcome: what the reader now has or sees.>

---

## <Next task, if the page covers a sequence>

---

## Next steps

<DocCardGroup cols={2}>
  <DocCard title="<Title>" href="/path/" label="<why the reader would follow it>" />
</DocCardGroup>
```

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](/en/documentation/style-guide/writing/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](/en/documentation/style-guide/writing/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](/en/documentation/style-guide/content/multi-product-guides/).
- **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:

```mdx
You can create an [Object Storage](/en/documentation/platform/object-storage/) bucket and change its permissions from Azion Console, the Azion CLI, or the API.

## Prerequisites

To use the CLI procedures, you need the Azion CLI installed and a configured personal token.

---

## Create a bucket

<Tabs client:visible sharedStore="interface">
    <Fragment slot="tab.console">Console</Fragment>
    <Fragment slot="tab.cli">CLI</Fragment>
    <Fragment slot="tab.api">API</Fragment>

<Fragment slot="panel.console">

To create the bucket from Azion Console:

1. Access [Azion Console](https://console.azion.com/) > **Object Storage**.
2. Select **+ Bucket**.
3. Enter a **Bucket Name** between 6 and 63 characters.
4. Set **Workloads Access** to _Read Only_, _Read-Write_, or _Restricted_.
5. Select **Save**.

The bucket appears in the bucket list.

</Fragment>

</Tabs>
```

- [Create request and response rules](/en/documentation/guides/application-development/getting-started/rules-engine/): two tasks on one page, each a named procedure with numbered imperative steps.

## Related

- [Tutorials](/en/documentation/style-guide/content/tutorials.md): The page for the reader who is learning.
- [Troubleshooting pages](/en/documentation/style-guide/content/troubleshooting.md): The how-to whose task is a fix.
- [Reference](/en/documentation/style-guide/content/reference.md): Where every setting a guide touches is documented.