People don't read help articles from top to bottom. They scan for the next step, follow it and get back to work. Here's how to write articles that let them do that, with a before and after example.
Write for someone in the middle of a task
Your reader has one question and wants to get back to what they were doing. Every sentence should help them do that. Leave out company history, feature marketing and anything they don't need for this task.
Use titles people would search for
The title is how people find the article: in your help center's search, in search engines and in AI answers. Write it in the reader's words.
For a task, start with a verb: "Export your invoices", not "Exporting".
For a problem, describe what the reader sees: "A client didn't get their invoice".
For a quick question, ask it: "Can I change my plan later?"
Skip clever titles, and feature names readers don't know yet.
Lead with the outcome
The first sentence says what the reader will get done and why they'd want to. If they need something first, such as a certain plan, a role or a file, say so right after, before the steps. Nobody should reach step 4 and find out they can't finish.
Make every step easy to follow
Number the steps. A numbered list shows the order and helps readers keep their place.
One action per step. "Click Save" is a step. "Choose a format, add a date range and click Export" is three.
Say where, then what. "In the top-right corner, click Export" tells readers where to look before what to do.
Bold the exact labels. Spell buttons and menu names exactly as they appear on screen, so readers can match them.
Warn before the step, not after. "Deleting a client also deletes their invoices" belongs before the step where they click Delete.
Say what happens. After an important step, tell readers what they should see, so they know it worked.
Keep it short and plain
Speak to the reader directly, in the present tense: "You can export…", not "Users are able to export…".
Keep paragraphs to one to three sentences.
Choose common words: "start" instead of "commence", "help" instead of "facilitate", "about" instead of "regarding".
Explain a term the first time you use it, or link it to your glossary.
Use the active voice: "We email you a link", not "A link will be emailed".
Plain writing also translates better, and gives AI answers less room to misread you.
Show the screen when it helps
A screenshot or a short GIF helps when a button is hard to find or a step involves movement, like dragging. Put it right after the steps it shows. Keep the steps complete in the text too: search, screen readers and AI can't read what's only in an image. See Use screenshots and GIFs well.
Plan for when things go wrong
End how-to articles with a short troubleshooting section: the problems people run into most, each with its fix. Quote error messages exactly as they appear, because people search for them word for word.
Point to what's next
Finish with links to related articles: the next task, the setting they'll want to change, the article that explains a concept. In the text, link a term to its article the first time it appears, not every time.
Review it regularly
An article is only as good as its last review. When the product changes, update the steps, labels and screenshots on the same day. For stable articles, set a date to check them again, and follow the steps yourself when you do. See Keep your help center up to date.
Before and after
Here's a typical first draft, and the same content rewritten with these rules.
Before
Exporting data
In order to export data, users should navigate to the Reports section, which is located in the main menu. There are several formats available and it is possible to choose between them. Please note that only users with admin rights are able to perform exports, and that large exports may take some time to process. Once processing has been completed, the file will be sent.
After
Export your invoices
Download your invoices as a CSV or PDF file for your accountant or your own records. You need the Admin role to export.
In the main menu, click Reports.
Click Export.
Choose CSV or PDF, then click Start export.
We email you a download link when the file is ready. Large exports can take a few minutes.
What changed
The title names the task in the reader's words.
The first sentence says what they'll get and why they'd want it.
The requirement comes before the steps instead of hiding at the end.
Each step is one action, and the labels match the screen.
The last lines set expectations: what happens next, and how long it takes.
Checklist before you publish
The title matches what people would search for.
The first sentence says what the reader will get done.
Requirements come before the steps.
Each step has one action, with UI labels in bold, spelled as on screen.
Warnings come before the steps they apply to.
Screenshots show the current screens.
Common errors have a fix in a troubleshooting section.
Related articles are linked.
Someone will review it when the product changes.
How HelpCenter.io helps
The HelpCenter.io editor includes article templates, such as How-to guide and Troubleshooting flow, so every article starts with the right shape. Callouts make warnings stand out, and the editor tells you when a similar article already exists. With AI writing help (Catalyst, or the AI add-on), you can simplify or shorten a selection and see the change before it's applied. See Start from an article template, Highlight tips and warnings with callouts and Write faster with AI writing help.
Comments
Be the first to comment.