Here's a test that takes ten seconds and ruins your afternoon.

Open one of your own help articles. Pick a section from the middle. Cover everything above it and everything below it, and read only that section.

Does it answer something completely? Could you tell which product it belongs to? Does it lean on a word like "above", "earlier" or "as mentioned"?

Most people fail on the third question, on the first section they try, and it's genuinely uncomfortable because the article looked fine.

Nobody reads your article from the top

They arrive from search, land halfway down, and read one section. That was already true when the reader was a person. It is now literally true for the machine answering on your behalf, which retrieves passages rather than pages.

So the writing is rarely the problem. We very seldom read an article and think the sentences are bad. What we find instead is a well-written piece where the answer is buried in paragraph six, the steps assume a setting you configured two articles ago, and the section headings describe topics rather than questions.

Three structural faults, in order of cost

The answer is not near the top. If the article is called "Can I do X?", the first line should say yes or no. Context can come after. Most articles do this backwards, building up to an answer like a story.

Sections depend on each other. "Once you've done the above" is the single most common way a good article becomes unusable in pieces. Repeat the condition instead of referring back to it. Yes, it feels redundant. It's redundant for the person who read from the top, and essential for everyone else.

Headings name topics, not questions. "Permissions" tells a reader nothing. "Who can delete a project" matches what someone actually typed, which is what both a search index and a retrieval system are matching against.

The fix is boring and it works

Write each section as though it's the only thing anyone will read. Put the answer first. Repeat the conditions. Use headings that sound like questions.

None of that is new advice for good documentation. What's new is the penalty for ignoring it, because the reader who lands mid-article can no longer scroll up.

The free article template gives you the shape to start from, and the free pre-publish checklist has twenty-four things worth catching before you hit publish.