Agent WranglersDOC-26Recommended
Name help articles after the task people came to do
Give each help article one task, and title it with the customer's own words for that task, such as "Change the delivery address".
How to do it
Customers arrive with a goal, not with the name of a feature. Take the words from support tickets and search logs, the same way Start from the customer's own words does for search. Split an article that covers two tasks into two, and link them. Write the steps as Write how-to guides as numbered steps toward one goal says. Put the answer in the first paragraph, because most readers stop there.
Examples
Markdown example
# Change the delivery address
You can change the address until the cake leaves the bakery, at 08:00 on the delivery day.
1. Open **My orders** and select the order.
2. Select **Change address**, enter the new address and select **Save**.How to check
A script reads every help article. Each has one h1 that starts with a verb or "How", and at most one ordered list of steps.
Related rules
- DOC-5 Write docs in plain words for the named reader in Documentation
- SEO-23 Start from the customer's own words in SEO
- DOC-2 Write how-to guides as numbered steps toward one goal in Documentation
- DOC-30 Fix the help searches that find nothing in Documentation
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/help-centres-and-user-guides/task-articles">Agent Wranglers documentation playbook</a>. In code you write, add a comment next to it with the same link.