How to Write a Help Centre Article

An article covering one task, structured so a reader who landed on it from a search result can finish that task without opening anything else, and a verification pass that catches the steps you left out because you already knew them.

Before you start

Write down the task in the words a customer would use, and the state they are in when they need it. "Change the card you get billed on" is a task. "Billing settings" is a screen, and articles named after screens are found by nobody.

Search your existing help centre for that task first. Half of all new articles are a section that belongs in an article that already exists, and the other half reveal that an existing article is covering three tasks and needs splitting.

Perform the task yourself, in the product, with the interface open, and write the steps as you go rather than afterwards. Instructions written from memory are missing the confirmation dialog, the loading state, and the second click that you have stopped noticing.

The last block is the one most articles omit and readers most need.

Steps

1. Title the article after the task, in the reader's language.
   Start with a verb where you can. Internal feature names in titles are a common cause of an article that ranks for nothing and is found by nobody browsing.

2. Open with the outcome, in one sentence.
   What the reader will have when they finish. A reader who cannot confirm in four seconds that they are in the right place goes back to the search results.

3. List the prerequisites before step one.
   Permissions, plan tier, anything that must already be set up. A prerequisite discovered at step six is the most reliable way to lose a reader who was doing everything right. Name the starting point too - "From the project dashboard" - so step one is not ambiguous for a reader who arrived from a different screen than the one you had open.

4. Give one action per numbered step, starting with a verb.
   Select, open, enter, confirm. Two actions in one step is where readers lose their place, because they complete the first half and read the whole step again looking for where they got to. Reserve numbers for order: a numbered set of options reads as a sequence, and readers perform all of them. Options get bullets.

5. Name every control exactly as the screen names it.
   Save changes is not "Save". If your product says Members, the article never says "Users". Approximate labels are the single most common reason a correct article fails its reader.

6. State where each control lives before naming the action.
   "In Settings > Billing, select Update card." Location first means the reader's eye finds the control before the instruction runs out.

7. Say what each step produces.
   A confirmation banner, a new row in a table, an email. Without it a reader has no way to know whether step four worked before committing to step five.

8. Pull conditionals out of the sequence.
   A step that begins "If you are on the legacy plan" interrupts everyone who is not. Move branches to sub-steps under a clearly labelled parent, or to a separate procedure. Stop at around nine steps for the same reason: a longer sequence is two procedures with a boundary in the middle, and the split belongs where the reader could stop and come back tomorrow.

9. Cover the two or three ways it goes wrong.
   The permission the reader lacks, the field that rejects certain characters, the change that takes a few minutes to appear. These are what the support ticket would have been about.

10. Close by confirming success.
    One sentence describing the end state, and one link to the single most likely next task. A list of twelve related links is a menu, and readers treat it as one.

11. Follow your own article on a clean account.
    Do the task exactly as written, on an account with none of your context. Every article contains at least one step the author performed without noticing, and this is how you find it.

One action per step. The reader is counting, not reading.

Common mistakes

Documenting the feature instead of the task. An article describing what each field on a screen does answers a question nobody typed into a search box.

Bundling actions with "and". The most common defect in procedural writing, and the easiest to find: search your draft for steps containing "and then".

Writing everything about a topic on one page. A 3,000-word article covering setup, configuration, troubleshooting and billing is four articles that are individually findable.

Explaining before instructing. Rationale ahead of the instruction gets skimmed past, and the reader scrolls looking for the numbered list. Put the reason after the action, if at all.

Publishing without doing the task. Articles written from memory of a feature you built are confident, plausible and missing the step where a dialog appears.

When this stops scaling

Writing one good article is a craft problem. Running a help centre is an inventory problem, and it changes shape around thirty to forty articles.

Below that, one person knows what exists and roughly whether it is still true. Above it, nobody does. Coverage gaps stop being visible - you cannot notice the absence of an article for a feature you did not think about - and currency stops being observable, because nothing connects the release that renamed a button to the six articles that mention it. Add a weekly release cadence and the library drifts faster than any individual can review it, without ever looking broken.

The signal to watch for is the first time somebody answers a support ticket by writing the explanation out by hand while an article on the same subject already exists. That means the library is no longer trusted, which is a harder problem than an empty one. Generating drafts from the codebase and flagging articles when a merged change touches the code behind them is how SupportPages approaches it. Under thirty articles with one owner, writing each by hand is entirely sustainable.