How to write task-based help articles

Your users don’t arrive at your help centre wanting to learn about a feature. They arrive wanting to do something: change their opening hours, invite a teammate, export last month’s invoices. They type that goal into the search box, or into a ticket, in their own words.

Many help centres are organised the other way round. There is an article per screen or per feature, “The Settings page” or “About Integrations”, and the reader has to work out which one holds the steps they need. A task-based article starts from the goal instead. It has one job, and it ends when the user has done that job. Here is a checklist for writing them.

Start from the questions users actually ask

The best list of article titles is already in your help desk. Each “how do I…” ticket names a task at the moment a user got stuck. If you have run a support ticket audit, your ranked list of tasks is your writing plan: start at the top.

If you haven’t, read a few weeks of tickets and your help centre’s search log, and write down the goals people describe. Keep their words. A user who searches “add a holiday” will not find an article titled “Managing availability exceptions”.

One task per article

The first rule is the one that changes the most. Each article covers a single task that a user could describe in one sentence.

• Too wide: “Team management”. It holds inviting, removing, changing roles and transferring ownership.
• Right size: “Invite a teammate”, “Change a teammate’s role”, “Remove someone from your workspace”.

If an article has more than one place where a reader might say “done”, split it.

The shape of a task article

Every task article can follow the same five parts, in the same order.

1. Step 1Title as a goalA verb phrase in the user’s words›
2. Step 2Before you startRole, plan or setup needed›
3. Step 3Numbered stepsOne action per step›
4. Step 4What you’ll seeThe result that means it worked›
5. Step 5If you’re stuckCommon snags and who to ask

1. Title it as the goal

Start with a verb, in the words your users use: “Change your opening hours”, “Connect your calendar”, “Export invoices as CSV”. Avoid nouns on their own (“Opening hours”) and avoid your internal names for things unless users say them too.

2. Say what they need before they start

One or two lines, only if it matters. “You need to be an admin.” “This is on paid plans.” “Connect a calendar first.” Saying this up front saves a user from following six steps and hitting a wall on the seventh.

3. Write numbered steps, one action each

Each step is one thing the user does. Name the control the way it appears on screen, in bold: “Select Settings, then Availability.” Start each step with a verb. If a step has an “and” in the middle, it is probably two steps.

4. Show the expected result

End the steps with what the user should see when it worked. “Your new hours show on your booking page straight away.” This is the part most often left out, and it is the part that stops a user from wondering whether they did it right, or from writing in to check.

5. Say where to go if stuck

List the two or three snags you see in tickets, each with its fix. “Don’t see Availability? Ask an admin in your workspace.” Then say how to reach a person, with a link.

A before and after

The same content, written two ways.

Feature-based	Task-based
Title: “Availability settings”	Title: “Change your opening hours”
Describes every option on the page	Covers only the steps to change hours
The reader finds their part of the page	The reader follows steps 1 to 4
Ends when the options are described	Ends with “your new hours show on your booking page”
No next step if it goes wrong	“Not seeing the change? Check your time zone”

Feature reference pages still have a place. They suit readers who want to understand everything a screen can do. Keep them, and link to them from the task articles for anyone who wants more.

The checklist

Run each article through this before you publish it:

1. The title is a goal, starting with a verb, in the user’s words.
2. The article covers one task, with one finishing point.
3. Anything needed beforehand (role, plan, setup) is in the first lines.
4. Steps are numbered, one action each, starting with a verb.
5. Buttons and menus are named exactly as they appear on screen, in bold.
6. The expected result is stated after the last step.
7. The common snags from tickets are listed with their fixes.
8. There is a clear way to reach a person.
9. The article links to related tasks (“Next: invite a teammate”).
10. Someone who has never done the task has followed it, unaided, on the live product.

Keep articles true as the product changes

Task articles go stale when the screens they describe change. A renamed button or a moved menu breaks step three, and the reader has no way to know the article is wrong rather than them.

A few habits help:

• Tie articles to releases. When a screen changes, list the articles that mention it and check each one before the release ships.
• Watch the ticket tags. If tickets about a task you have already documented start to rise, re-read the article. Something on screen has probably moved.
• Re-test the top articles each quarter. Follow the steps on the live product, start to finish, as a new user would.

When users would rather ask than read

A good task article makes a task findable. It still asks the user to leave what they were doing, read, then go back and follow along step by step. For a lot of tasks that is fine. For short, repeated, safe tasks, many users would rather say what they want and have it done.

That is where an in-app agent fits, alongside your articles. Stiro is one. You add it to your app with one script tag, with nothing to train. A user types or says “change my Saturday hours to 10 to 2”, and Stiro does the steps in your real interface while they watch.

• It does the steps your article lists. The user asks for the goal, the same goal your article is titled with, and Stiro clicks and types through the screens.
• It reads the live screen. When a button is renamed or a menu moves, it works from what is there now, so there is nothing of its own to keep in step with your releases.
• It says so when a request can’t be done. It stops, says why and changes nothing.
• The user keeps the final say. Anything that sends, spends or deletes is set up and handed back for the user to press.
• Stuck still leads to a person. A signed-in user can message your team from the same panel, with the request attached, or it goes to your help desk.

everyday requests passed, cold, in three apps it had never seen

44 of 44

on a repeat run of the same code

43 of 44

The benchmark tasks are the kind a help centre documents: change an event’s length, add a buffer, update a record. The benchmark page lists every task and reply. Your articles stay useful too: for users who prefer to read, for the tasks that need judgement, and as the way you learn which tasks people struggle with.

Start with your top five tasks

Pick the five tasks users ask about most, and rewrite those articles with the checklist above: one task, numbered steps, the result, and where to go if stuck. Then, for the short and repeated ones, add Stiro to your app and let users ask for them directly. The free plan includes 50 runs a month, so you can try it on those same five tasks first.