How to write help articles an AI assistant can answer from

Practical rules for help content that a retrieval-based assistant can find, quote and cite correctly: titles, headings, wording, numbers and synonyms.

Guide · Updated · by the Citewell team

In short

Write one topic per article with a title that matches the customer’s question, put the answer in the first paragraph, use the words customers use (including synonyms), and state numbers and limits explicitly. Retrieval-based assistants can then find and cite the right passage.

An assistant that answers from your help content is only as good as that content. Most "the AI got it wrong" problems are really "the article never said it clearly". This guide collects practical rules for writing articles that a retrieval-based assistant such as Citewell can find, quote and cite correctly. They also make the articles better for people.

How the assistant reads your articles

It helps to know what happens to your text. In Citewell:

  1. Each article is split into passages of about 160 words. Markdown headings stay with the text under them.
  2. A question is matched to passages by keywords, using word stems (so *cancelled* matches *cancel*) and synonym groups.
  3. If the best passages don't contain enough of the question's important words, the assistant doesn't answer; it offers a person.
  4. Otherwise the top passages go to the model, which must answer only from them and cite them.

So two things matter most: the right words must be in the passage, and the answer must be complete inside roughly 160 words. The how answers work article has the full details.

Rule 1: one question per heading

Write headings as the question a customer would ask, or as the topic in their words:

  • Good: "Can I change my delivery address after ordering?"
  • Weak: "Order modifications"

A heading travels with its passage, so it adds the right keywords exactly where the answer is.

Rule 2: answer in the first sentence

Put the answer first and the explanation after it. "Yes, within 30 days of delivery, if the item is unused." is a passage that can stand alone. A passage that starts with background and reaches the answer in the third paragraph may be split away from it.

Rule 3: use your customers' words, then add synonyms

If customers say "money back" and your article only says "reimbursement", the match is weaker. Use the common word in the text, and add synonym groups for the rest (Knowledge base → Synonyms, one group per line). Common support pairs such as refund and money back, log in and sign in, shipping and delivery are already built in. The glossary explains how synonym matches are weighted.

Rule 4: state numbers and conditions explicitly

Write "Refunds are issued within 5 working days" rather than "Refunds are quick". Citewell checks that every number in a written answer appears in the passages it was given; vague text means the assistant can't give a precise answer, and a number it isn't given will be rejected. Repeat key numbers in each article that needs them instead of saying "see our refund policy".

Rule 5: one topic per article

An article titled "Billing FAQ" that covers cards, invoices, VAT, refunds and cancellations produces passages that are about several things at once. Split it. Each source keeps its own public link, so citations then point customers to the right page.

Rule 6: say what you don't do

Customers ask about things you don't offer: "Do you ship to Iceland?", "Can I pay with PayPal?". If the answer is no, write it down: "We don't ship outside the GCC." Otherwise the assistant correctly says it couldn't find an answer and escalates, which costs your team a ticket.

Rule 7: keep it current

When a policy changes, update the page and re-fetch it in Citewell (or edit the pasted text). Old and new versions side by side are the fastest way to get contradictory answers. Delete sources you no longer stand behind.

A before-and-after example

Before:

Our flexible returns process is designed with you in mind. Contact us to start.

After:

Can I return an item? Yes. You can return unused items within 30 days of delivery. Start a return from the link in your order email. Return shipping is free in the UAE; elsewhere it is paid by the customer. Refunds go back to the original card within 5 working days of the item arriving.

The second version answers six likely questions, contains the numbers, and fits in one passage.

Test like a customer

In the playground, ask each question three ways: the way your team says it, the way a customer says it, and with a typo or a short phrase ("return sale item?"). Check which passages are cited. If the wrong article wins, change its heading or add the missing words. Then watch Analytics → Unanswered after launch; it is your list of articles to write next. For a worked example of a store's policy pages, see Citewell for online stores.

Try Citewell free

A help assistant that answers from your own articles, shows its sources, and hands off to your team when it is not sure. The Free plan needs no card; you can export or delete your data any time.