# Reference

## Purpose

A reference page is look-up material. The reader consults it to find one value, one field, or one limit, and then leaves.

## When to use

Write a reference page when:

- The reader needs to look up a field, a setting, a limit, or a flag.
- The information is enumerable and fits in a table.

Do not write a reference page when:

- The reader needs steps for a task. Write a [how-to guide](/en/documentation/style-guide/content/how-to-guides/).
- The reader needs the reasoning behind a design. Write a [concept](/en/documentation/style-guide/content/concept/).

## Register

Descriptive: 25 words per sentence, active voice, passive only when the actor is unknown. Tone: plain, neutral, exhaustive. [Sentence structure](/en/documentation/style-guide/writing/sentence-structure/) holds the rules.

## Structure

**Required components**

- **Title**: a noun phrase naming the thing: `Object Storage`, `Cache settings`, `azion create bucket`.
- **Opening move**: one to three definitional sentences about the artifact, then straight to the data. No procedure framing.
- **Sections**: noun-phrase `##`s naming the actual object, field group, or level. Tables carry the information — fields, values, defaults, limits — with consistent phrasing down every column and units on every number. Prose between tables is one or two sentences of orientation.
- **Limits**: a `## Limits` section when the product has them, **dimensioned by plan**. Use `| Scope | Plan | Limit |` when a scope repeats across plans, or one column per plan when the set is short enough to read across. Every row carries its unit and says whether the limit is hard or raisable.
- **Closing**: `## Related resources`, a `DocItem` list covering the concept page and the main how-tos, each row with its reason.

**Optional components**

- **Asides**: a tip above the limits table when support can raise the limits, and a caution for a version or migration warning. Use no other aside.

The sections keep this order.

When the limits set grows large enough to consult on its own, it moves into its own Limits slot in the product section. These rules do not change: only the location does. [Information architecture](/en/documentation/style-guide/content/information-architecture/) holds the slot list.

## Template

Copy the template and replace each `<placeholder>`:

```mdx
import FrameBox from '@aziontech/webkit/frame-box'
import ItemList from '@aziontech/webkit/item-list'
import DocItem from '@aziontech/webkit/doc-item'

**<Product or resource>** is <one to three definitional sentences about the artifact>.

## <Object, field group, or level, as a noun phrase>

<One or two sentences of orientation.>

| Field | Description |
| --- | --- |
| <Field name> | <What it holds, with the default value> |

## <Object, field group, or level, as a noun phrase>

<...>

---

## Limits

:::tip
Support can raise the limits marked raisable. Contact <support link>.
:::

| Scope | Plan | Limit | Raisable |
| --- | --- | --- | --- |
| <Scope> | <Plan name> | <Value with the unit> | Yes / No |

---

## Related resources

<FrameBox>
<ItemList>
  <DocItem title="<The concept page>" href="<url>"><why the reader would follow it></DocItem>
  <DocItem title="<A main how-to>" href="<url>"><why the reader would follow it></DocItem>
</ItemList>
</FrameBox>
```

## Rules

- **Never a numbered click-through.** The moment one appears, the page is a [how-to guide](/en/documentation/style-guide/content/how-to-guides/) filed wrong. Link the how-to instead.
- **Be complete before you are interesting.** A reference missing three of twelve fields is broken; one with dull descriptions of all twelve is doing its job.
- **Put enumerable information in tables.** Fields, limits, flags, defaults, status codes.
- **Keep phrasing consistent down a column.** Readers scan; varied phrasing forces them to read.
- **State the units and the defaults.** A limit without a unit is not a fact.
- **Dimension every limit by plan.** A limit that differs across plans is not one fact. A number published without the plan it belongs to is wrong for every reader on a different plan.
- **Distinguish a limit from a default.** A default is a field value and belongs in the field table. A limit is a ceiling and belongs under `## Limits`.
- **Say whether each limit is hard or raisable.** The reader's next action depends on it: a raisable limit is a support request, a hard limit is a design constraint.
- **Never invent a limit or a plan name.** Take both from the pricing page, the plans agreement, or the product team. A value you cannot confirm is not published: narrow the table to the dimensions you can confirm.
- **Never restate a price.** Amounts, quotas sold by the unit, and billing metrics live on the pricing page alone. Link it; do not copy it.
- **No marketing.** Say what it does and where it stops.
- **A CLI command page has its own shape.** A one-line summary, then `## Usage` with the command, then `## Optional flags` with one entry per flag.

## Examples

This excerpt of a reference page for **Object Storage** shows the definitional opening, one object section with its table, and the closing:

```mdx
import FrameBox from '@aziontech/webkit/frame-box'
import ItemList from '@aziontech/webkit/item-list'
import DocItem from '@aziontech/webkit/doc-item'

**Object Storage** is a Store product that stores objects in buckets. A bucket is the container; an object is the stored item plus its metadata. Azion stores all buckets in the _us-east_ cloud region and bills storage per GB/hour, with no minimum retention.

## Buckets

Bucket names follow these rules:

| Rule | Value |
| --- | --- |
| Length | 6 to 63 characters |
| Characters | Alphanumeric characters and hyphen |
| Reserved prefix | Must not start with `azion` |
| Uniqueness | Exclusive across all Azion accounts |

You cannot rename a bucket. You can delete a bucket only when it is empty, 24 hours after the removal of the final object.

## Related resources

<FrameBox>
<ItemList>
  <DocItem title="Create an Object Storage bucket" href="/en/documentation/guides/application-development/data/create-and-modify-bucket/">create a bucket and set its `workloads_access` permission.</DocItem>
  <DocItem title="Use a bucket as origin" href="/en/documentation/guides/application-development/data/use-bucket-as-origin/">serve content from a bucket through Connectors.</DocItem>
</ItemList>
</FrameBox>
```

This excerpt shows a limits table where the breakdown by plan was not confirmed. The table carries the columns that were confirmed and no more:

```mdx
## Limits

:::tip
Support can raise the limits marked raisable. Contact the [technical support team](/en/documentation/support/).
:::

| Scope | Limit | Raisable |
| --- | --- | --- |
| Buckets | 100 per account | Yes |
| S3 credential access keys | 100,000 per account | Yes |
```

The missing column is the point. The breakdown by plan for these numbers was not confirmed, so the table has no plan column rather than an invented one.

## Related

- [Choose a content type](/en/documentation/style-guide/content/choose-a-content-type.md): The full catalogue of page kinds.
- [Tutorials](/en/documentation/style-guide/content/tutorials.md): The content type that teaches through a first project.
- [How-to guides](/en/documentation/style-guide/content/how-to-guides.md): The content type that holds the steps.
- [Concept](/en/documentation/style-guide/content/concept.md): The page kind that holds the reasoning.
- [Documentation voice](/en/documentation/style-guide/writing/voice.md): The one register every page uses.