Documentation Experience League Authoring Guide

Steps and lists steps

Last update: August 26, 2026

Procedures (also called tasks or exercises) answer How do I…? questions. They use a predictable structure so readers can finish a goal without guessing what to do next. Conceptual context belongs before the numbered list—either on the same page, in a parent section, or on a parent topic (see Concepts and tasks in Editorial guidance for Experience League authors and Structure and organize content in Create a page in Experience League). Procedures in hands-on exercises follow the same rules as product documentation tasks.

At a glance

Scope. This page covers bullet lists, list punctuation, rules for numbered procedures, Markdown list syntax, what belongs in a task, task headings, verbs for describing the UI, complex procedures, single-step procedures, field and option descriptions in steps, and how lists support AI discovery.

How to use this page

Authors: Skim Quick rules, then open the section you need from On this page.
Automation and reviewers: Treat Quick rules and Must bullets under each heading as hard requirements. Should and May are guidance.

Quick rules quick-rules

Topic

Rule

Bullets

Use when order does not matter; keep items parallel; use one punctuation style for the whole list.

Numbered steps

One action per step, imperative mood, complete sentences. Split or nest when a procedure grows beyond about seven steps (up to ten is acceptable if every step stays one clear action).

Concept vs. procedure

Put prerequisites and explanatory copy before the steps. Do not bury full procedures inside concept-only sections without a clear task heading.

UI in steps

Use UICONTROL for interface strings (bold in published steps). Repeat page, tab, or panel names so readers stay oriented.

Screenshots

Place a screenshot on the line after the step that reveals the UI (see Screenshots).

AI discovery

Put task language in real sentences inside steps; use structured lists so search and AI tools can quote procedures accurately (see Write for AI discovery (lists and steps)).

Bullet lists bullet-lists

Purpose. Bulleted lists group related items when sequence does not matter.

Must

Introduce the list with a complete sentence or clear lead-in that ends with a colon when it flows into the list.

Should

Keep items short and in parallel form (same grammatical pattern).

Example

The database owner can:

Create and delete a database.
Add, delete, or modify a document.
Add, delete, or modify any information in the database.

Punctuation in lists list-punctuation

Purpose. Consistent punctuation keeps lists easy to scan and to localize.

Must

Do not end list items with semicolons, commas, or conjunctions such as and or or when those items are meant to read as a simple series.
Do not add a period to an item unless it is a complete sentence—or unless any item in the same list needs sentence-style punctuation (then use periods consistently for all items in that list when they combine with the introduction to form full sentences).

Should

When the lead-in is a fragment ending with a colon and all items combine with it to form complete sentences, end every item with a period.

Examples

Product managers can:

Confirm or remove topics that were discovered in your tenant.
Create new topics manually as needed.
Edit existing topic pages.

Exceptions

Omit periods when every item has three or fewer words, or when items are UI labels, headings, subheadings, literal strings, or similar.

The files for upload customer attributes include:

companylist.csv
update.pdf

See also — Punctuation and emphasis.

Numbered procedures step-guidance

Purpose. Numbered lists are sequential procedures: readers follow order to reach one goal.

Must

Write one action per step in a single concise sentence (or use a colon when the step introduces a sub-list). Put step results, notes, and images on the next line, indented under that step (see Complex procedures).
Begin with the action. Use the imperative (Create a segment.). When orientation helps, you may state the goal first (To create a Fallout report, click New.)—some linters flag this pattern; use it only when it reduces ambiguity.
Keep conceptual information (including prerequisites) before the first numbered step. If you need more than about a paragraph of context immediately before the steps, add a concept heading for that block, then a task heading for the procedure.
Place screenshots immediately after the step that shows the result (see Screenshots).
Repeat page, tab, or panel names in steps so readers know where they are. Articles (the) are optional when the name is enough:

* On [page name], click…
* On _Page views report_, locate…
* On the Activities page, find…
* On Activities, enable the following options…

Where UI labels are easy to misread, pair italics with UICONTROL. Reserve bold UICONTROL for controls you click or act on in the step.
Capitalize the first word of each step. End each step with a period unless the step is only user-typed input that should not show a trailing period—then put the literal input on its own indented line.

Should

Treat about seven steps as a practical ceiling for a single procedure. If readers need more, split into separate tasks, add substeps, or restructure after a short task analysis.

May

Combine tiny actions that happen in the same place in the UI into one step when the sentence stays clear.

Create steps in Markdown (syntax) markdown-syntax

Purpose. Markdown renders ordered lists from repeated 1. markers; you do not hard-code final numbers.

Must

Start each step line with 1. (the processor supplies 1, 2, 3…).

Should

Indent nested lines to create substeps. Blank lines between top-level steps are optional; keep nesting consistent so the build output is stable.

Syntax

1. This is step 1.
1. This is the next step.

   1. This is a sub-step
   1. This is a sub-step

1. This is yet another step, the third.

See also — Numbered lists and bullet lists.

Tasks: content and headings task-content

Purpose. A task bundles navigation, screen context, controls to use, and short field or option explanations so someone can complete work in the product.

Must

Use UICONTROL with bold for interface elements in procedures (see Localization).
Use sentence case for task headings (see Headings).

Should

Choose structure by scope: large features often use a parent concept page with child task pages; small features may use one page with a concept H1 and task H2 sections.

Example (TOC pattern)

Experience Cloud audiences (concept page)
 Create an audience (task page)
 Share an audience to Adobe Analytics (task page)

See also — Concepts and tasks, TOC entry for a task article.

Describe the interface ui-verbs

Purpose. Consistent verbs reduce ambiguity in steps and in localization.

Should

Use Open for applications and programs (Open the Segments panel.).
Use Close for applications and programs (Close the Dimensions window.).
Use Leave for websites and pages (Leave Report Builder.).
Use Go to (or From the … menu) to move the reader to a tab, menu, or location.
Use Select for highlighting text or cells and for picking a value from a list.
Use Click for mouse or equivalent primary actions (Click Find.). Avoid naming the control type (button, link) unless the type matters for clarity or accessibility—labels change less often than control types.

Complex procedures complex-step

Purpose. Long or branching work may need substeps, brief orienting labels, or a split into multiple tasks.

Must

Use one numbered entry per step unless you deliberately combine very short actions in one place in the UI.
Prefer complete sentences and imperative verbs.
Keep parallel structure when you repeat patterns such as On the … panel, ….

Should

If substeps sprawl, re-analyze the task and break it into smaller procedures or pages.
When you need a short orienting line before the numbers, you may use a step heading that mirrors the task heading—for example, task H2 Configure processing options with a line To configure processing options before 1. only when it genuinely helps scanning.
Include actions that complete a change when the product requires it (Save, OK, Apply).

Examples

On the Calendar panel, select Today.
To specify a date, select Calendar.
For Alignment, choose Left.

Example (published task)

Sample complex procedure.

See also — Numbered procedures.

Single-step procedures single-step

Purpose. A procedure with only one action should not look like a multi-step list.

Must

Use a bullet, not 1., when there is exactly one step and your template allows it—while keeping the same imperative style as multi-step tasks.

See also — Steps and bullet lists.

Fields and options fields-options

Purpose. Steps are the right place to document how to reach a control and what it does in context—not long conceptual articles mixed into navigation.

Must

Keep step-by-step navigation and field definitions inside task content. If you are adding numbered navigation to a concept, overview, or FAQ, move that content to a task topic or section.
Use bold UICONTROL for controls so readers can scan; put definitions next to the control or in the same step.

Example

field descriptions

See also — UI control (UICONTROL).

Write for AI discovery (lists and steps) ai-lists-steps

Purpose. Structured lists are easy for humans to follow and for search and AI tools to extract as procedural answers. Lists and steps should carry plain language that stands on its own.

Must

State the action and the goal in step text—not only in screenshots. Models and snippets read the visible sentence, not the image.
Use real sentences for each step so an extracted line is still a valid instruction.

Should

Match Write for AI discovery on the editorial page: complete metadata, self-contained headings, synonyms on first use when helpful, and short, direct sentences.
Prefer numbered steps for true sequences and bullets for parallel options—structure signals intent to both readers and systems.

See also — First paragraphs, SEO, Description metadata.

recommendation-more-help

authoring-guide-help-main-guide