Practical guide

Writing docs your AI can actually use

Teams usually blame the model when a support AI gives vague answers. Far more often the problem is the documentation it was given. These are the rules that make the difference - and they'll make your help centre better for humans too, which is the nice part.

How Grounding Works Download Free Evaluation

First, the rule that explains the rest

ZChat picks the passages to give the model by matching words from the visitor's question against your documents. It is keyword scoring, not semantic embedding search. That single fact drives everything below: the AI can only use a document it manages to find, and it finds documents that share vocabulary with the question. Write the way your customers write, not the way your engineers do.

1. One question per document

A file called "Refunds" that answers one question will beat a 40-page policy manual every time. When several topics share a document, the passage that gets retrieved is often the wrong half of it. Split by the question a customer would ask, not by the structure of your product.

2. Use your customers' words - including the wrong ones

Your document says "authentication failure". Your customer types "can't log in". Because matching is word-based, that document may never surface. Include the phrasings people actually use, mistakes and informal names included: "login", "sign in", "password not working", and whatever your customers call your features when they get the name wrong.

3. Lead with the answer

Put the fact in the first line, then the caveats. "Refunds are available within 30 days of delivery" is a usable answer; three paragraphs of context ending in the number is not. Only a fragment of your document reaches the model, so the answer should be in the part most likely to be picked.

4. Write what a model cannot guess

The AI already knows what a refund is. It cannot know your refund window, your supported firmware versions, or which of your settings fixes the most tickets. Specifics are what earn their place - general advice is what the model already has.

5. Keep the marketing out

Promotional copy dilutes the useful text and drags answers toward the language of a brochure. The knowledge base is for facts, procedures and policies. Your best-converting page is rarely your most answerable one.

6. Date anything that expires

A model has no idea a document is out of date - it will answer from a superseded policy with complete confidence. If something changes seasonally or by version, say so in the text, and diarise the review.

The same content, rewritten

Hard for the AI to use	Easy for the AI to use
"Our commitment to customer satisfaction means we handle returns fairly and promptly."	"You can return an item within 30 days of delivery for a full refund. Opened software is excluded."
A single "Troubleshooting" file covering twelve unrelated problems.	Twelve short files, each named for the problem a customer would describe.
"Authentication failures may result from credential mismatch."	"Can't log in? If your password isn't working, reset it here. Accounts lock after 5 failed attempts."

Let your history choose

Don't guess what to write first

ZChat tags finished conversations automatically, so your most frequent tags are a ranked list of what customers actually ask - which is a far better writing queue than anyone's intuition. Start at the top and work down. See AI summaries and tagging.

Fixing is editing

No training run. Correct the document and the next answer is correct - so treat bad answers as documentation bugs.

Humans benefit too

Short, specific, plainly-worded articles are better for the people reading your help centre as well. Nothing here is a compromise.

How long should each document be?

Short and single-purpose beats long and comprehensive. One question per file, answered in a few paragraphs, retrieves far more reliably than a 40-page manual where the relevant sentence is buried on page 31.

Why does the exact wording matter so much?

ZChat finds relevant passages by matching the words in the visitor's question against your documents - it is keyword scoring, not semantic embedding search. So a document that says 'authentication failure' will not be found by someone asking why they 'can't log in'. Write both.

Should I include marketing copy?

No. Promotional language dilutes the useful text and pulls answers off-course. The knowledge base should hold facts, procedures and policies - the things a general-purpose model cannot possibly know about your product.

How do I know which documents to write first?

Let your own history tell you. ZChat's AI tags finished conversations, so the most frequent tags are your most-asked topics - and therefore the documents worth writing first.

How do I fix a bad answer?

Edit the underlying document. There is no training run, so the corrected wording takes effect immediately. If the AI answered badly because no document covered the question, that gap is itself the thing to write.

Owned customer support software

Deploy live chat on your own terms, not on someone else's pricing model.

ZChat gives you the installable server, web dashboard, website widget, and desktop agent tools in one self-hosted product you buy once and keep. Run it on infrastructure you trust and connect AI only if and how you want it.

Download ZChat See Product Demo

Deployment

Install on Windows or Linux, behind IIS or Nginx, in a VM, or in Docker if that fits your stack.

Commercial model

One-time purchase, perpetual license, and no monthly per-agent bill attached to growth.

AI Flexibility

Use Ollama locally or connect OpenAI and Anthropic with your own provider accounts.