Structure and navigation

Organize a page around what the reader needs to understand or do. Someone arriving from search needs enough context to identify the product, version, subject, and next action without reading the rest of the site first.

Choose the right page

Use a procedure for a task with an ordered sequence. Use a concept page to explain a mechanism, a reference page for facts readers look up, and troubleshooting for a symptom and its supported recovery paths. A tutorial can combine these forms, but should introduce each idea near the step that needs it.

A short answer may fit beside a control or in one paragraph. A longer subject may need separate pages with a clear route between them. Choose the form for the information; do not add a video, diagram, or table merely to vary the page.

Before drafting, identify the audience, starting knowledge, intended result, required evidence, and publication surface. Include translation and accessibility needs at this stage. A page intended to help someone recover work needs a different opening from an announcement.

Make headings an outline

Give each page one descriptive title. Use real heading levels for its sections, with lower levels describing parts of the section above. Task headings name actions; concept headings name subjects. Keep sibling headings parallel when they serve the same purpose.

Read the headings without the body text. Their order should reveal the page's scope and progression. If two headings repeat the same promise, combine the sections or distinguish their jobs. Do not fill the gap between adjacent headings with a sentence that adds nothing.

Start a section with the information it promises. A heading called “Export formats” needs the available formats and their relevant differences, not another introduction to exporting. Put a prerequisite before the step that depends on it.

Let headings wrap naturally on narrow screens. Use styles for spacing instead of manual line breaks. A short heading can still be unclear; retain the words that distinguish this topic from its neighbors.

Choose lists and tables for their relationships

Use a numbered list when sequence or ranking matters, and bullets for related items without an order. Keep items grammatically parallel. A list need not reach a target length: split it when separate groups would help the reader, not because it has passed an arbitrary count.

Make each item understandable without completing a fragment in the introduction. This gives translators room to change word order. Full sentences take periods; short labels or noun phrases usually do not. Use one treatment for comparable items.

A table compares the same attributes across several items. Name each column and give the reader enough context to understand the comparison. A single set of names belongs in a list; a long explanation usually belongs in prose.

Distinguish an empty value from None, Unknown, and Not applicable. These mean different things. Do not fill an unknown value with a dash that leaves the reader guessing. State units in column headings when the units apply to the whole column.

Keep a wide table usable at narrow widths or with enlarged text. If the reader must scroll horizontally, its labels and relationships must remain understandable. Do not force every cell onto one line by removing necessary words.

Help readers find and resume the page

Use the terms readers use in titles, headings, and descriptions. Include a technical synonym where it helps someone connect a search term with the preferred term. Repeating keywords without adding information makes a page harder to read.

Give long pages a linked contents list. Link to the specific related task or explanation, and explain an unfamiliar term briefly in place when that saves an unnecessary detour. See task guidance for link placement and prerequisite handling.

An aside or sidebar contains supplementary material. It must not hold a required step or a condition needed to interpret the main text. A pull quote keeps its original meaning and clear attribution; it does not supply evidence for a claim the speaker never made.

Review the reading order

Read the title, headings, and first sentence of each section. Then follow the page from a realistic entry point, such as a search result or a link to a subsection. Repair missing context, repeated explanations, and unexplained jumps.

Inspect the page on a narrow screen and with enlarged text. Check the order when columns stack, the relationship between captions and images, and whether a task remains understandable without its illustrations. A successful build verifies links and markup; it does not prove that the page answers the reader's question.