Procedural writing — the numbered steps that walk readers through a task — is the most read content type in most knowledge bases. It is also the content type with the most specific formatting requirements. A procedure that is structured correctly is easy to follow. A procedure that is structured poorly stops readers mid-task.
The Anatomy of a Procedure
A well-formed procedure has four parts, in this order:
- Goal statement: One sentence that states what the reader will accomplish by the end of the procedure.
- Prerequisites: Everything the reader needs to have or know before they begin. Anything that, if missing, would cause the procedure to fail partway through.
- Steps: The numbered actions the reader takes.
- Result: What the reader sees or has when the procedure is complete.
Not every procedure needs all four parts. A simple three-step procedure might not need a prerequisites section. A very straightforward task might not need an explicit result statement. But consider each element and include it when it adds value.
Writing Individual Steps
One action per step
Each numbered step should describe exactly one action. When a step contains two actions, readers lose their place — they complete the first action, look back at the step, and cannot tell whether they have already done the second part.
| Two actions in one step (avoid) | One action per step (prefer) |
|---|---|
| 3. Click the Settings icon and select Account from the dropdown menu. | 3. Click the Settings icon. 4. Select Account from the dropdown menu. |
The exception: if two actions are so closely linked that separating them would feel artificial, they can stay together. "Press and hold the Shift key while clicking the items" is one conceptual action even though it involves two physical movements.
Start each step with a verb
Every step starts with an imperative verb — the action the reader takes. The UI element or location comes after the verb. See the Verbs, Tense, and Mood guide for the full rule on imperative mood and verb choice; the examples below are that same rule applied specifically to procedural steps.
| Wrong order | Correct order |
|---|---|
| The Save button should be clicked. | Click Save. |
| Under Settings, navigate to the Users tab. | Go to Settings, then click Users. |
| Your name field needs to be updated. | Update your name in the Name field. |
State the result after the action when useful
When a step produces a visible change — a new page loads, a dialog opens, a confirmation appears — tell the reader what to expect. This helps readers verify they have completed the step correctly and reduces anxiety about whether something has gone wrong.
Example: "Click Save. The record updates and a confirmation message appears at the top of the page."
Do not state a result for every step — only when the result is something the reader needs to notice or verify.
Steps that require waiting
If a step triggers a process that takes noticeable time — a file processing, a build completing, changes propagating — say so, and give an approximate duration if you have one. A reader who clicks something and sees no immediate change needs to know whether that's expected or a sign something went wrong.
Example: "Click Import. This can take a few minutes for large files. The status updates to Complete when the import finishes."
Conditional steps
When a step only applies in certain situations, state the condition before the action. See the condition-before-action guidance in the Verbs, Tense, and Mood guide for the general rule; applied to a procedural step, it looks like this:
| Condition after action (avoid) | Condition before action (prefer) |
|---|---|
| Click Enable two-factor authentication if you want additional security. | If you want additional account security, click Enable two-factor authentication. |
Branching procedures
Sometimes a procedure genuinely splits into two or more distinct paths that don't reconverge — for example, different steps for an Admin versus a Member, or a different flow depending on plan tier. Don't force a single branching step ("if X, do this; if Y, do that") to carry an entire divergent sequence.
- If the branches are short (one or two steps) and reconverge quickly, a single conditional step or a brief sub-branch is fine.
- If the branches are long, or never reconverge, split them into clearly labeled sections with their own H3 headings ("If you're an Admin" / "If you're a Member"), or into entirely separate articles if the audiences and contexts are different enough — see the Knowing Your Audience guide for how to decide when separate content per audience is warranted.
Step Count and Article Length
A procedure with more than 10 steps is usually either covering too much ground in one article, or including sub-steps that should be separated from the main sequence.
When a procedure genuinely requires more than 10 steps:
- Group steps into phases using H3 headings: "Phase 1: Configure your settings" / "Phase 2: Invite your team"
- Consider whether the procedure is actually two or three procedures that should be separate articles
Sub-Steps
Sub-steps (a, b, c or nested numbering) are acceptable for brief clarifying actions that belong under a main step but are not themselves full steps. Use them sparingly and limit to one level of nesting.
Example:
- Go to Settings.
- If you are on a mobile device, tap the menu icon first to access Settings.
- Click Users.
Optional Steps
If a step is optional, label it explicitly at the start of the step. Do not assume readers will infer that a step is optional from context.
Correct: "(Optional) Enter a description for the category."
Correct: "Optional: Enter a description for the category."
Screenshots Within a Procedure
Not every step needs a screenshot. As a general guideline:
- Include a screenshot at points of genuine ambiguity — a step involving a UI element that's easy to miss or a screen with many similar-looking options.
- Skip screenshots for simple, unambiguous steps ("Click Save") where an image adds bulk without adding clarity.
- For a long procedure, a single screenshot per phase (rather than per step) is often enough to orient the reader, with individual step-level screenshots reserved for the trickiest moments.
- Position each screenshot immediately after the step it illustrates, not before it or grouped at the end of the procedure. See the Media Guidelines section of the Formatting Standards guide for image quality, alt text, and file naming requirements.
Connecting to Troubleshooting
If a particular step is a common point of failure — a permission error, a validation issue, a step that behaves differently across browsers — link to the relevant troubleshooting article directly at that step, rather than waiting until the end of the procedure or assuming the reader will search separately. See the Five Core Content Types guide for when a problem is significant enough to warrant its own troubleshooting article rather than a note within the procedure.
Procedure Template
The following template provides a starting structure for any procedural article. Adapt it to fit the specific task — add sections you need and remove sections you do not.
[Article title — starts with a verb or "How to": e.g., "Creating a new category"]
[One-sentence goal statement: what the reader will accomplish.]
## Before you begin
[List any prerequisites: access levels, prior steps, or information the reader needs.]
## Steps
1. [First action. Result if needed.]
2. [Second action. Result if needed.]
3. [Continue for each step.]
[Final result: what the reader has or sees when the procedure is complete.]
[Optional: next steps, related articles, or troubleshooting link.]
Self-Audit Checklist
Before publishing, check the procedure against these questions:
- Does the procedure open with a one-sentence goal statement?
- Are all prerequisites listed before the first step, if any exist?
- Does every step describe exactly one action, except genuinely atomic combined actions?
- Does every step start with an imperative verb?
- Are results stated only where the reader needs to verify something happened?
- Do steps that trigger a wait or delay say so, with an approximate duration if known?
- Do all conditional steps state the condition before the action?
- If the procedure branches by role, plan, or platform, are the branches clearly separated rather than crammed into one conditional step?
- Is the procedure under 10 steps, or split into phases/separate articles if it exceeds that?
- Are sub-steps used sparingly and limited to one level of nesting?
- Are optional steps explicitly labeled as optional?
- Is each screenshot placed immediately after the step it illustrates, and included only where it adds clarity?
- Are common failure points linked to a troubleshooting article at the relevant step?
- Does the procedure end with a clear result statement?