How long should a help article be for AI?

As long as one task or question needs, and no longer. Most good help articles are 150 to 600 words. Length matters less than focus: a long article covering one task works; a short one covering five doesn’t.

Do AI assistants read screenshots?

Most help centre assistants answer from text and see at most an image’s alt text. Write every instruction as text and use screenshots to support it.

Should I write separate articles for AI and for people?

Rarely. What helps an AI, clear titles, one topic and exact names, helps people too. Keep separate AI-only guidance for things you want followed but not published, such as how to handle an exception.

Why does the AI give a wrong answer when the article is right?

Usually another article says something different, the right section isn’t found because it uses different words from the question, or the key condition is in a heading, a picture or another section. Find the source it cited and fix that.

How to write help articles AI can answer from

To write help articles AI can answer from, cover one task or question per article, title it the way customers ask, put the answer in the first paragraph, use descriptive headings, name plans, settings and buttons exactly, and keep every instruction in text rather than only in screenshots. Then test with real customer questions.

None of this is new advice for help writing. AI makes it matter more, because an assistant reads your help centre the way a search engine does: in pieces, by matching words and meaning. Habits that people forgive, such as long pages and a vital detail in a screenshot, make an AI miss the answer or give half of it.

How an AI assistant reads your articles

Most AI assistants for help centres use retrieval: they split each article into sections, find the few sections that best match the question, and answer only from those. That has three consequences for writers.

A section has to make sense on its own. If “click Save” only means something after reading the three sections above it, the AI may get the instruction without the context.
The words matter. A section is found by matching the question’s words and meaning. If customers say “cancel” and your article only says “terminate your agreement”, it may not be found.
Only text counts. Most retrieval reads the words on the page, and at most an image’s alt text. Anything you only show in a picture or video isn’t there.

For more on the moving parts, see what an AI knowledge base is.

One topic per article

An article called “Billing” that covers plans, invoices, refunds, VAT and failed payments is hard for people and harder for retrieval: every billing question matches it a little, and none matches it well. Split it so each article answers one question or covers one task.

“How to change your plan”
“Downloading invoices”
“Adding your VAT number to invoices”
“Refunds: who can get one and how”
“What happens when a payment fails”

A useful test: can you say what the article answers in one sentence? If you need “and” twice, it’s probably two articles. Link them to each other instead of merging them.

Titles and headings

Title it the way customers ask

Customers search for tasks and problems, not for the names of your features. “Why didn’t my export download?” is found by people who have that problem. “Export module overview” isn’t.

Answer first

Put the answer in the first one or two sentences, then the steps and details. An AI assistant often uses the opening of a section to decide whether it answers the question.

Headings that say what’s underneath

Headings are where articles get split, so each heading should describe its section on its own. “Step 2” or “More information” tells nobody anything. “Connect your domain’s DNS” does. Keep headings in order (H2, then H3) rather than picking sizes for looks.

Exact names, numbers and conditions

The AI will repeat what you write as precisely as you write it. Vague articles produce vague answers, and ambiguous ones produce wrong answers.

Name things exactly as the product does

Use the button, menu and setting names exactly as they appear on screen, including their capitals, and give the path: Settings → Billing → Invoices. If a name changed, mention the old one once (“Teams, previously called Groups”) so people searching for the old name still find it.

State plans, limits and prices precisely

“Available on higher plans” forces the AI to guess. “Available on Growth and Business” doesn’t. The same goes for limits (“up to 10 team members”), periods (“within 30 days of payment”) and prices, including the currency and whether tax is included. Keep each of these facts in one article and link to it from the rest, so a change is one edit.

Write the conditions out

Spell out who something applies to and when. “Admins can export data” leaves the AI to work out what happens for everyone else. “Only admins and owners can export data. Members see the Export button greyed out” answers the follow-up before it’s asked.

Say what isn’t possible

Customers often ask about things your product doesn’t do. If nothing says so, an assistant that answers only from your articles has to decline, and one that doesn’t may guess. A short line such as “There’s no offline mode: the app needs an internet connection” answers the question honestly.

Use your customers’ words too

If customers call it “the QR thing” and you call it “dynamic codes”, include their phrase once, naturally: “Dynamic codes (the QR codes you can edit after printing)…”. Some tools also let you add search phrases to an article without showing them.

Text, not just pictures

Screenshots and videos help people, but an AI assistant reading text can’t see them. Every instruction should work without the picture.

Write each step as a sentence, then add the screenshot after it.
Give every image alt text that says what it shows (“The Billing page, with Download invoice on the right”).
For a video, add a written summary or the steps underneath it.
Avoid PDFs and attachments for anything important. Put the content in the article.

FAQs, tables and lists

FAQs

Short question-and-answer pairs suit AI well: the question matches how people ask, and the answer is short enough to quote. Use them for the small facts that don’t deserve their own article, but don’t hide a whole procedure in an FAQ answer. Each answer should make sense without the question’s heading around it, so start with “Yes” or “No” plus the fact, not “It depends”. If you publish FAQs on your website, our guide to adding FAQ schema shows how to mark them up.

Tables

Tables are good for comparisons, such as which plan includes what. Give every column a clear header, because a row on its own (“Yes | 10 | No”) means nothing without them. Keep one fact per cell, and don’t merge cells.

| Plan     | Team members | Custom domain |
|----------|--------------|---------------|
| Starter  | 3            | Yes           |
| Growth   | 10           | Yes           |

Numbered steps

Use a numbered list for any procedure, one action per step, with the result where it helps (“Click Save. The page shows Changes saved.”). Steps written as a paragraph are harder to follow and harder to quote.

Test with real questions

You can’t judge an article for AI by reading it. Ask the questions customers actually ask and look at what comes back.

Take twenty recent support emails and ask each question in the customer’s own words, typos and all.
Check that the answer is right, complete, and cites the article you expected.
Ask things your articles don’t cover. The assistant should say it doesn’t know, not improvise.
When an answer is wrong, find the sentence that misled it. The fix is usually in the article, not the AI.
Ask the same question a few ways (“cancel”, “stop paying”, “delete my account”) and check they reach the same article.

Keep the list of questions and rerun it after big changes to the help centre. It works as a regression test for your documentation, and it’s the fastest way to see whether an edit helped.