proc-003 should GuidesAPI docs Write procedures as numbered steps; use a bulleted list for single-step procedures.
Procedures
A procedure is a sequence of steps a reader performs, often while switching between the docs and their own screen. These rules cover how to number, phrase, and order steps so readers always know where to act, what to do, and which steps they can skip. General list formatting lives on the lists page.
Number steps; bullet a single step
Section titled “Number steps; bullet a single step”Examples
- ✓ - Click Refresh to reload the data.
- ✗ 1. Click Refresh to reload the data.
Rationale
Numbered steps show sequence and let the reader track their place; a single step needs no number.
Steps are complete sentences
Section titled “Steps are complete sentences”proc-001 should GuidesAPI docs Each step in a numbered procedure should be a complete sentence with sentence-style capitalization and closing punctuation.
Examples
- ✓ 1. Click Save.
- ✗ 1. click Save
Goal before action
Section titled “Goal before action”proc-005 should GuidesAPI docs State the condition or goal of a step before the action so readers can skip steps that do not apply to them (‘To start a new document, click File > New’).
Examples
- ✓ To start a new document, click File > New.
- ✗ Click File > New to start a new document.
Rationale
Stating the goal first lets a reader skip a step that does not apply to them.
Location before action
Section titled “Location before action”proc-004 should GuidesAPI docs State the location or context of an action before stating the action itself within a procedural step.
Examples
- ✓ In the Settings pane, click Advanced.
- ✗ Click Advanced in the Settings pane.
Rationale
Naming where to act before the action lets the reader find the control before doing anything.
Marking optional steps
Section titled “Marking optional steps”proc-006 should GuidesAPI docs Mark optional steps with ‘Optional:’ (not ‘(Optional)’) at the beginning of the step.
Examples
- ✓ 1. Optional: Add a description.
- ✗ 1. (Optional) Add a description.
Rationale
A leading “Optional:” tells the reader up front that they can skip the step.
Keyboard shortcuts outside steps
Section titled “Keyboard shortcuts outside steps”proc-002 should GuidesAPI docs Do not include keyboard shortcuts within step-by-step procedures; reference them separately if needed.
Examples
- ✓ 1. Click Save.
- ✗ 1. Click Save (or press
Ctrl+S).
Rationale
A keyboard shortcut inside a step distracts from the primary path, so keeping it separate keeps the step clean.
Link instead of repeating
Section titled “Link instead of repeating”proc-007 should GuidesAPI docs Avoid repeating procedures; instead, reference and link to them.
Examples
- ✓ Create a service account by following the steps in Create a service account.
Rationale
Repeating a procedure creates copies that drift, so linking to one keeps a single source of truth.