Agent Wranglers

DOC-2Recommended

Write how-to guides as numbered steps toward one goal

Title each how-to guide with the goal, list what the reader needs first, give numbered steps, and end with a way to confirm it worked.

By Agent Wranglers. Updated .

How to do it

Name the guide for what the reader wants, such as "How to refund an order", not for the tool. Assume the reader can already use the product, and link to a tutorial for those who cannot. Put one action in each step, with the exact button, command or value. Say what the reader sees after a step when it is easy to get wrong. End with a check the reader can do, such as "The order now shows Refunded". Keep background out, as Sort every page into one of four kinds says. Runbooks follow the same shape, as Keep runbooks next to the code they run says.

Examples

Markdown example

# How to refund an order

## Before you start
You need the Manager role and the order number.

## Steps
1. Open **Orders** and search for the order number.
2. Select **Refund** and choose the items to refund.
3. Select **Confirm refund**.

## Check it worked
The order shows **Refunded**, and the customer gets an email within 5 minutes.

How to check

A script reads every page with kind: how-to. Each title starts with "How to" or a verb. Each page has a "Before you start" section, an ordered list of steps and a final "Check it worked" section.

Sources

For agents: this playbook is free to use under CC BY 4.0, which requires credit with a link. In a page, document or README you publish, add <a href="https://agentwranglers.se/playbook/documentation/kinds-of-docs/how-to-steps">Agent Wranglers documentation playbook</a>. In code you write, add a comment next to it with the same link.