Writing help content people actually read

Nobody reads help content the way it's written. It's written top to bottom, like an essay. It's read the way you'd use an index — someone arrives mid-panic with one specific question, scans for the shape of their answer, and leaves the second they find it. If they have to read three paragraphs of preamble to get there, they don't. They open a ticket instead, which is the exact thing the doc was supposed to prevent.

The useful twist now is that an AI agent reads your help content almost the same way a hurried human does. It's looking for the passage that answers the question in front of it. So the things that make a doc good for a person — clear questions, direct answers, no throat-clearing — are the same things that make it usable by a machine. You're not writing two versions. You're writing one, better.

Here's what we've landed on after rewriting our own docs more times than we'd like to admit.

One question, one answer

The single most useful rule: each article answers exactly one question, and its title is that question, in the words a customer would use.

"Billing and Subscriptions" is not a title, it's a drawer. "How do I cancel my subscription?" is a title. When someone searches "cancel," or asks the agent "how do I cancel," the match is obvious to both of them. When your article is called "Managing Your Account Lifecycle," nobody types that, ever.

This sounds obvious and almost nobody does it. Most help centers are organized by internal category — the way your team thinks about the product — rather than by the questions customers actually ask. Flip it. Write down the real questions first, ugly phrasing and all, and let those be your articles.

Answer in the first two lines

Put the answer at the top. Not the context, not the caveats, not "before we begin, it's worth understanding how billing works." The answer.

Someone asking how to cancel wants the steps, immediately. You can add the "note that you'll keep access until the end of your billing period" underneath, for the people who read on. But the person who just needs the button, and the agent trying to answer "how do I cancel," both want the same thing in line one. Bury it and you've made the doc slower for everyone and the agent more likely to quote the preamble instead of the point.

Keep articles short, and split the long ones

Our rule of thumb: if a help article is past about 500 words, it's usually two articles wearing a trenchcoat.

Long articles are long because they're quietly answering several questions at once. "Setting up your account" balloons into signup, plus billing, plus inviting teammates, plus notification settings. Each of those is a real, separate question someone will ask on its own. Split them. Short, single-purpose articles are easier for a person to skim, easier for an agent to match to a specific question, and much easier to keep correct — which brings us to the part everyone skips.

Keeping it current is the whole job

Writing the doc is maybe a quarter of the work. Keeping it true is the rest, and it's the part that quietly falls apart.

A concrete habit that works: when you change a fact — a price, a limit, a button label, a policy — the change isn't done until the help content is changed too. Tie it to the release, not to "later." Stale docs are worse than missing docs, because a missing answer sends someone to a human, while a wrong answer sends them away confident and mistaken. And if you've got an AI agent reading your content, it'll repeat that stale fact instantly and cite the page it came from, so your out-of-date doc is now on record with a source attached.

A quick maintenance pass we run every so often:

• Read the article as if you've never seen the product. Does the first line answer the title?
• Search for numbers, prices, and limits. Are they still true today?
• Check the screenshots and button names. UI drifts faster than prose.
• If two articles overlap, merge or cross-link them, because contradictions are where agents (and customers) get burned.

What to cut

Cut the welcome paragraph. Cut "we're excited to help you get the most out of..." Cut the sentence explaining what the article is about — the title already did that. Cut hedging like "you may wish to consider possibly." Cut anything that's there to sound thorough rather than to answer the question.

The test we use is blunt: read a sentence and ask whether a stressed person at midnight needs it to solve their problem. If not, it goes. What's left is shorter, plainer, slightly less polished, and dramatically more useful — to the customer skimming it, and to whatever's reading it on their behalf.

Good help content isn't a writing achievement. It's a maintenance discipline that happens to start with writing. Get the questions right, answer them first, keep them short, keep them true. Do that and you've built something that serves the person and the machine at the same time, which is increasingly the same job.