Procedures

The first step

Every numbered procedure in the documentation follows these rules, whatever kind of page it sits on. The first rule consolidates access and navigation into one step. Do not make “Log in” its own step when the next step is going somewhere.

Console procedures start with the canonical string:

Fill in the product: > **Object Storage**, > **Firewall**. Deeper navigation extends the chain: > **Applications** > **your application**.

A single-command procedure is not a numbered list. Write one lead-in sentence ending in a colon, then the command:

Numbering starts when the procedure has two or more actions. An API procedure’s lead-in names the method and endpoint: “Send a POST request to the buckets endpoint:” then the curl block.

One action per step

A step holding two actions is a step where the second one gets skipped.

• Incorrect: Select **Save**, then purge the cache and confirm the TTL changed.
• Correct: three numbered steps, one for each action.

Small movements that form one gesture may share a step, and therefore one sentence: Enter a name and select **Read Only**. This is the one place a single sentence carries two imperatives, and it overrides the sentence rules in Sentence structure.

Order within a step

The reader orients, then acts. Location comes before the action:

• Incorrect: Select **Add Rule** in the Rules Engine tab.
• Correct: In the **Rules Engine** tab, select **Add Rule**.

Purpose comes before the action. When a step exists for a reason the reader cannot see, lead with it: To delete the rule, select **Delete**.

Condition comes before the action: If the list is empty, select **Add**.

Step grammar

• Write in the imperative, active, present: Select **Save**. Never “You should select” or “The Save button should be selected.”
• Start an optional step with the literal word (Optional): 3. (Optional) Enter a description for the rule.
• Mark sub-steps with lowercase letters (a., b.) and sub-sub-steps with lowercase Roman numerals. If a step needs sub-sub-steps, the procedure wants splitting.
• Bold the UI label and italicize the UI value: Set **Workloads Access** to _Read Only_.
• Use the interface verbs only: select, go to, turn on, turn off, enter. Not click, hit, enable, disable. The table is in Word choice.
• Use the interface’s own words. If the button says Save, the step says select Save, not “confirm” or “apply”. Do not improve on the interface’s vocabulary in prose that describes it.
• Do not use directional language. Name the element, not where it sits on the screen, per Accessibility.
• Keep each sentence at 20 words and each step at one instruction. The procedural budget is in Sentence structure.

The lead-in

Directly before the numbered list, one sentence states the goal and ends in a colon:

Use a colon when the sentence immediately precedes the steps. Use a period when material sits between them, such as an aside. Never write a partial sentence that the steps complete.

After the procedure

End every procedure with one outcome sentence. State what the reader now has or sees, so they can tell they succeeded without asking.

• The bucket appears in the bucket list.
• The response returns "state": "executed" with the bucket name.

When the interface shows no output, state the resulting state instead: The bucket has the new access level. Never write interface output, response codes, headers, or messages you have not seen the product produce. That distinction is what separates an outcome sentence from an invented fact.

Warn about timing. If a result takes time to propagate, say so and say what to do: “New rules can take a few minutes to propagate. On an unexpected response, wait and retry before diagnosing.”

Follow-on tasks go in the page’s ## Next steps section, never in a “post-requisites” section.

Show the expected output

Every command the reader runs is followed by the output they should see. Show the complete output when it is short, and the relevant excerpt when it is long. The output confirms the step worked before the next step depends on it.

Input and output take different blocks: a <Code> block for the command the reader copies, a fence for the output they read. The mechanics are in Components.

When a command produces no output, state the resulting state instead. When you can state neither, cut the command or restructure the step around a result the reader can check: a command the reader cannot verify is worse than one less command. Never write output you have not seen the command produce.

Multiple interfaces

When a task has a Console, CLI, and API path, the paths go in a <Tabs> block: one procedure per panel, Console first. Each panel opens with its own lead-in naming the interface: To create the bucket with the Azion CLI:. The steps or the command follow directly, and the lead-in is never restated as a step. Never interleave two interfaces in one numbered list. The mechanics of the <Tabs> block are in Components.

Include a panel only when you have run its procedure end to end. Leave out an interface you cannot verify yet, rather than filling its steps from the other panels.