# 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**: 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>`.

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

```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

<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">

### Console

- Access to [Azion Console](https://console.azion.com/).

</Fragment>

<Fragment slot="panel.cli">

### CLI

- The Azion CLI installed and a configured personal token.

</Fragment>

<Fragment slot="panel.api">

### API

- A personal token and `curl`.

</Fragment>

</Tabs>

---

## Create a bucket

<Tabs client:visible sharedStore="interface">

<Fragment slot="panel.console">

### 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.