Help center · Writing

How to write help articles people actually read

Nobody reads a help article for fun. They arrive stuck and a little annoyed. A good article gets them unstuck in the first few lines.

Title it like the search

People search in their own words, so use them. “How do I change my email address?” or “Change your email address” both work. “Account identity settings” doesn't.

Check your inbox for how people describe the problem. If they say “invoice,” don't call the article “Billing documents.”

Answer in the first two lines

Put the answer at the top. Many readers will stop there, and that's a success.

Weak start: “At [Product], we believe managing your account should be simple. In this article, we'll walk you through…”

Good start: “To change your email, open Settings → Account, type the new address and select Save. We'll send a confirmation link to the new address.”

Then add the details below, for the people who need them.

Write steps you can follow with one hand

• One action per step.
• Use the exact button and menu names from the app.
• Say what the person should see after a step, if it isn't obvious: “A green Saved message appears.”
• Number the steps when the order matters.

Cover the “it didn't work” part

Most help articles stop at the happy path. The person reading often isn't on it. Add a short part at the end: “Don't see the email? Check your spam folder, wait five minutes and try again. Still nothing? Write to us.” This one paragraph answers a lot of follow-up messages.

Screenshots: helpful, but not alone

A screenshot helps when a screen is busy or a button is hard to describe. But don't let an image carry the instructions. Text can be searched, read aloud by screen readers, and fixed in a minute when the app changes. A screenshot needs a new capture every time you move a button.

If you add one, crop it tight around the part that matters.

One article, one task

“Managing your account” that covers email, password, billing and deleting the account is four articles in one. Split it. Short articles are easier to find, easier to link in a reply, and easier to keep up to date.

A checklist before you publish

1. Does the title use the customer's words?
2. Is the answer in the first two lines?
3. Did you follow the steps yourself, in the current version of the app?
4. Is there a line for when it doesn't work?
5. Does it link to the one article people usually need next?

In MVPKit, every article gets its own page and link on your project's help center, so you can paste it into a reply. Articles sit in categories, and visitors can search them.