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.
• The reader needs the reasoning behind a design. Write a concept.

Register

Descriptive: 25 words per sentence, active voice, passive only when the actor is unknown. Tone: plain, neutral, exhaustive. 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 holds the slot list.

Template

Copy the template and replace each <placeholder>:

Rules

• Never a numbered click-through. The moment one appears, the page is a how-to guide 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:

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:

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