Skip to main content

Writing good knowledge

Almost every problem with AI answers is a knowledge base problem. The assistant is faithful to what it is given: an ambiguous article produces an ambiguous answer, and a missing article produces a hand-over.

This page is about what to write, not about the mechanics of adding it. For those, see Articles.

One question, one article​

The unit that retrieves well is a question a customer would actually ask.

Not "Shipping and returns policy" covering both. Two articles: "How long does delivery take" and "How do I return an item". A customer asking about delivery should not be given a passage about returns to read past.

If an article's title needs an "and", it is probably two articles.

Answer in the first sentence​

Retrieval finds passages, and the passage that gets used is often the first one in the article. Put the answer there.

Before

Our shipping process has been designed with care to ensure that every customer receives their order in perfect condition. We work with several logistics partners across Europe, and our warehouse team packs each bike by hand. Delivery normally takes three to five working days.

After

Delivery takes 3-5 working days inside Germany, Austria and the Netherlands, and 5-8 working days elsewhere in the EU. Bikes in stock leave the warehouse within two working days.

The second version answers the question. The first buries it under sentences that also happen to look relevant to a search.

Be specific, including about the exceptions​

Vague articles produce vague answers, and vague answers produce a second email.

Before

Refunds are processed promptly once we receive the returned item.

After

Refunds are issued to the original payment method within five working days of the item arriving back at our warehouse. Bank transfers can take a further three days to appear.

The exceptions matter as much as the rule. If island addresses add three days, say so in the shipping article — otherwise the assistant will confidently promise the standard window to somebody on an island.

Write what is not covered​

The assistant will not invent a boundary you did not state.

Bikes ship to all EU member states plus Switzerland, Norway and the UK. We do not ship bikes outside Europe. Spare parts without batteries can go worldwide at cost.

Without the middle sentence, a customer in Canada gets either a hand-over or, worse, an answer assembled from the parts of the article that do apply.

Keep numbers, names and codes exact​

Full-text search matches literal strings. Model names, part numbers, error codes and price points should appear in the article exactly as customers write them — including the variants. If people call it both "Trail 5" and "Trail-5", having both in the article costs one word and saves a failed search.

Use the customer's words, not yours​

Internally the policy is called "RMA process". Customers write "how do I send it back". Semantic search bridges a lot of that gap, but not all of it, and a title in customer language costs nothing.

Keep it current​

An out-of-date article is worse than a missing one. A missing article produces a hand-over; a wrong article produces a confident wrong answer.

This is the argument for synced sources over manual articles wherever you have the choice: a help center you already maintain cannot go stale in FirstReply without going stale for your customers first.

For manual articles, put a review in the calendar quarterly and delete anything you no longer stand behind. Deleting is a real fix.

Include the internal rules too​

Not everything the assistant needs is customer-facing. Manual articles are the right place for:

Tone. How your replies should sound, in the concrete rather than the abstract. "Open with the answer, not with an apology" is usable. "Be friendly and professional" is not.

Escalation rules. When a conversation must go to a person: money beyond a standard refund, an injury, a third occurrence of the same problem, or an explicit request for a human.

The things everyone knows. The exceptions your team learned by doing the job and never wrote down. Those are exactly what the assistant is missing.

A test worth running​

Take last week's twenty conversations. For each one, ask whether the knowledge base contains a passage that answers it.

Where the answer is no, you have found the article to write next — and you found it from real questions rather than from imagining which ones people ask.