Writing help articles people actually finish: 12 rules

Nobody reads a help article for pleasure. Your reader is in the middle of something, slightly annoyed, and wants to get back to work. These twelve rules come from that single fact.

Titles

1. Make the title the question. "How do I cancel my subscription?" beats "Subscription management". Readers scan titles in search results; a question that matches theirs gets the click.

2. Use the customer's words, not yours. If customers say "invoice" and your product says "billing document", write "invoice". Your list of searches that found nothing tells you which words they use.

3. One article, one question. An article that answers five questions answers none of them well — and search cannot point to the right one.

The first lines

4. Answer in the first sentence. "You can cancel at any time from Billing → Cancel plan." Then explain. Many readers stop after one line; let them.

5. Say who it applies to. "Only workspace owners can do this" or "Available on the Pro plan" belongs at the top, not at step 6.

Steps

6. Number procedures. Numbered steps are easier to follow and to refer to ("I'm stuck on step 3").

7. One action per step, in the order of the screen. Name the button exactly as it appears, in bold: Save changes, not "save".

8. Use screenshots sparingly. One screenshot where the interface is ambiguous helps; ten screenshots go out of date with your next release and make the article hard to scan.

Scanning

9. Use headings that are questions or tasks. Readers jump to the part they need; headings also become a table of contents.

10. Put warnings in a callout, before the step they apply to. A warning after the irreversible step is a post-mortem.

Deleting a workspace removes all of its articles. Export them first.

Maintenance

11. Date your articles and review them. An article that describes an old screen is worse than no article. Review the least helpful ones every few weeks.

12. End with a way out. If the article did not help, the reader should be one click away from a human: a contact link at the bottom turns frustration into a good ticket instead of a churned customer.

A template you can copy

# How do I <do the thing>?

You can <do the thing> from **Menu → Item**. <Who can do it / which plan>.

## Steps

1. Open **Menu → Item**.
2. Click **Button**.
3. Confirm with **Save**.

> [!NOTE]
> <The one thing people get wrong.>

## Related

- [The next thing people usually ask](/a/next-question/)

kbshelf's editor shows a live preview as you write, supports callouts like the ones above, and every article ends with "Was this helpful?" so you know which rule to apply next.