How to write help articles customers understand

Nobody reads a help article for pleasure. Customers arrive in the middle of a task, often from a search result, often on a phone, and they want one answer. They scan the page for it and leave. An article works when that scan finds the answer. Short sentences help, and a readability score measures them, but the bigger gains come from how the article is built. This guide covers the structure first, then the words, then how to test the result.

Start from the customer's question

Write the title as the customer would ask it. "How to change your billing email" matches what people type. "Billing contact management" matches your internal menu. Take the words from real sources: ticket subjects, chat messages and the searches people run in your help center.

Keep one task per article. An article called "Billing settings" that covers the billing email, the tax number, the invoice language and the payment method answers four questions badly. Four short articles, each with a title that is the question, answer each one well, and each can be linked from the place where the question comes up.

Put the answer in the first two sentences

Many readers stop after the first lines. Make those lines the answer: who can do it, where, and the result. The steps come after, for the readers who need them. "Only the account owner can change the billing email. Open Settings, then Billing." is a complete answer for a reader who only needs to know where to go. An introduction about why billing emails matter is an answer for none of them.

Put conditions and warnings before the step

Readers act on each step as they read it. A condition or a warning that comes after the step comes too late.

• Conditions first. "If you pay yearly, open Plan first." is safe. "Open Billing. (If you pay yearly, open Plan instead.)" is not: the reader is already on the wrong page.
• Warnings first. "Deleting a workspace removes all its data. This cannot be undone." belongs above the Delete step, not in a note at the end of the article.
• Who can do it, at the top. If only an admin or the account owner can do the task, say so before step 1, so other readers do not follow five steps to a button they cannot see.

Write steps the way the screen looks

• One action per step, numbered.
• Use the exact label on the screen, and mark it the same way every time, for example in bold: Settings, Save.
• Say where things are when the page is busy: "Select Edit next to Billing email."
• End with the result, so the reader knows the task is done.

When a label changes in your product, every article that names it is now wrong. Keep a list of the articles that name each screen, or search the help center for the old label after every release.

Use one word for each thing

If one article says "workspace", the next says "account" and the third says "organization" for the same thing, readers assume they are three different things. Pick one term for each concept and use it everywhere, including in the product. Our own documentation keeps a table of approved terms in its style guide for this reason, and it follows ASD-STE100 (Simplified Technical English), a writing standard with a limited vocabulary and short sentences.

Two more word rules help readers who are stuck. Leave out "simply", "just" and "easy": to a reader who could not do it, they read as blame. And define a term once, the first time you use it, in the same sentence.

An example rewrite

This is a real kind of help text: one sentence that tries to say everything.

In order to facilitate the modification of the email address that is associated with your billing account, it is necessary for the account owner to navigate to the Billing section of the Settings area, where the current address can be updated, after which a verification message will be sent to the new address, which must be confirmed before invoices are delivered there.

The readability checker counts 62 words in 1 sentence, a Flesch Reading Ease of 4.7 ("very difficult") and a Flesch-Kincaid grade of 28. The structure is worse than the score: the condition (only the owner can do it) is in the middle, and the step that is easiest to miss, confirming the new address, is at the very end.

The rewrite puts the condition first, splits the steps and ends with the result:

Only the account owner can change the billing email.

1. Open Settings, then Billing.
2. Select Edit next to Billing email.
3. Type the new address and select Save.
4. Open the email we send to the new address, and select Confirm.

Invoices go to the new address after you confirm it.

Now the checker counts 48 words in 6 sentences, a Reading Ease of 73.6 ("fairly easy") and a grade of 5. No fact is lost. "In order to facilitate the modification of" became "change", and the confirm step, which was hidden in a clause, is now a step of its own.

Screenshots support the text; they do not replace it

A screenshot helps a reader find a button. It cannot be searched, a screen reader cannot read the text in it, and it is out of date after the next redesign. Write every step in words first, then add a screenshot only where the screen is hard to read. Give each screenshot alt text that says what it shows.

Test with one real reader

A score tells you about sentence length. Only a reader tells you whether the article works. Ask a colleague who does not know the feature to do the task with only the article, and watch without helping. Each place where they stop, scroll back or ask a question is a fix. It takes five minutes and finds problems that no formula sees.

Then use the score as a gate for every new article. Paste the draft into the readability checker, rewrite the sentences it lists, and agree a minimum score for your team so that everyone writes to the same standard.

Find the articles that fail

An article fails when customers read it and still contact you. Three signals point to those articles: help center searches that end in a contact, tickets that quote or link an article, and questions that the article should answer but a chatbot could not. If you use Paperlink AI, the Unanswered report lists the questions the bot could not answer from your content, and Needs review collects the answers that visitors rated as not helpful. Because the bot answers only from your documents and pages, a clear article gives it a clear answer to quote, and an unclear one shows up in those reports. See how Paperlink AI finds gaps in your documentation.