Procedure
A procedure is the ordered sequence of steps that accomplishes the task. It is the working core of a tutorial or how-to page — the part the reader actually follows.
When to use
Use a procedure whenever the page's goal is to get the reader to do something. A page can have several procedures, each under its own H2 for a distinct phase of the task.
Composed of
- Headings — an H2 per phase; keep depth no deeper than H3.
- Ordered lists, or the
:::div[steps]atom for a visually distinct numbered sequence. - Code blocks — commands and code the reader runs.
- Tabs — parallel versions of a step (for example, SQL vs. Python).
- Admonitions — warnings and tips attached to a step.
Technical details
- Write steps as an ordered list. In Markdown, use
1.for every item and let the renderer number them, so reordering does not renumber by hand. - Group steps into phases under H2 headings when the task is long. Each phase should end at a checkpoint the reader can verify.
- Put commands and code in code blocks with a language for highlighting. When a step differs by language or cloud, use tabs.
- Bold UI labels exactly as they appear: "Click Create".
Rules
- One action per step. If a step has two verbs, split it.
- Each step must produce a result the reader can observe before the next step.
- Steps are imperative and second person: "Select the catalog", not "The catalog should be selected".
- Do not bury a required action inside prose between steps.
Style
- Start each step with the verb.
- Name what the reader will see after the action, so they can confirm success.
- Keep explanation to a sentence; move longer rationale to a concept page and link it.
Template
Markdown
## <Phase of the task>
1. <Imperative step. Names the result.>
1. <Imperative step.>
```sql
-- code the reader runs
```
1. <Imperative step.>
Examples
Create a catalog
- Click Catalog in the sidebar.
- Click Create catalog.
- Enter a name and click Create. The new catalog appears in the catalog list.