Optimize Your AI Assistant's Answers

Once your Assistant is set up and answering (see Set Up a Reverb 2.0 Target and AI Assistant), you can make its answers noticeably better by tuning three things you control: its Instructions, its Grounding Knowledge, and any Reasoning Fuel you add. This topic explains what belongs in each, and gives you a simple, repeatable way to test that a change actually helped.

The Three Things Your Assistant Works From

Knowledge Base is the Platform's name for the upload area on the Assistant's Configure tab. It is a container, not a kind of content: Grounding Knowledge and Reasoning Fuel are the two kinds of content you put in it, and everything uploaded there is one or the other. (ePublisher's Generate Knowledge Base target setting names something narrower — it produces the knowledge-*.zip archive, which becomes the Grounding Knowledge you upload.) The practical difference from Instructions is reliability: Instructions are always in effect, while Knowledge Base content is looked up per question, and a lookup can occasionally miss the right passage. That leads to one simple placement rule:

Rules go in Instructions; facts go in the Knowledge Base. Anything the Assistant must always get right — how it speaks, what it assumes, what it must never invent — belongs in Instructions. Reference material it should draw on when relevant — Grounding Knowledge and Reasoning Fuel alike — belongs in the Knowledge Base.

There is one more thing the Assistant sees, and only in your published help: the page the reader is viewing. Each chat message from published Reverb 2.0 output quietly includes the text of the currently open page, so readers can ask "What does this setting do?" and get an answer about that page. The Preview tab on the Platform does not attach any page — which is what makes it the right place for controlled testing — so after publishing, also try a few questions from the actual help pages where readers will ask them.

Write Instructions That Hold Up

Instructions are the Assistant's standing orders. Keep them short and direct — a page or less of plain statements works better than a long essay. Cover:

• Voice — "You are the product name documentation assistant. Answer in the product's own voice, as your own expertise."

• Defaults — what to assume when a question is ambiguous, and to say so: "When the output format is unclear, assume WebWorks Reverb 2.0 and state the assumption."

• Vocabulary — "Use the labels and values users see in the interface, not internal names."

• No source narration — "Never say where information comes from ('the docs say…'). State answers directly." Links to your published pages are added automatically — the Assistant does not manage them.

• No guessing — "Never invent setting names, values, or version details. If unsure, say what is uncertain or give the general approach."

When testing keeps showing the Assistant missing one critical fact, you can add that fact to the Instructions so it is always present. Use this sparingly — Instructions should stay short — but it is the reliable fix for a must-never-miss detail.

A Starting Point You Can Paste

You do not have to write Instructions from scratch. Paste the starter below into the Instructions field on your Assistant's Configure tab, replace the bracketed [PLACEHOLDERS], and you are done — everything else works as written. It covers the ground above and nothing more, which is the right size for a first Assistant.

You are the documentation assistant for [PRODUCT NAME]. You answer questions
from the product's published documentation, for people using the product.

Voice
- Answer in the product's own voice, as your own expertise. Be direct and practical.
- Lead with the answer. Put steps after it, numbered in the order the user performs them.
- Keep answers short. Answer the question that was asked, without padding.

Defaults
- When a question is ambiguous, assume [YOUR MOST COMMON CASE — FOR EXAMPLE:
  THE WEBWORKS REVERB 2.0 OUTPUT FORMAT] and say that you assumed it.
- Assume the user is on [CURRENT VERSION] unless they say otherwise.

Names
- Use the labels and values the user sees in the product interface, exactly as
  they appear there.
- Never invent setting names, values, file names, or version details. If you
  cannot confirm a name, say what is uncertain and describe the general
  approach instead.

Answering
- State answers directly. Never mention where information comes from — no
  "according to the documentation", no mentions of files, uploads, or searches.
- If the documentation does not cover the question, say so plainly and point
  to the closest topic it does cover. Do not guess.
- If the question is about the page the reader is viewing, answer about that
  page specifically.

Out of scope
- Do not answer questions about [TOPICS THE ASSISTANT MUST NOT HANDLE — FOR
  EXAMPLE: LICENSING, PRICING, OR ACCOUNT ISSUES]. For those, direct the user
  to [CONTACT OR CHANNEL].

Treat the starter as your Assistant's first version, not its final one: publish with it, build the question list described in Test with a Question List, and let what you observe drive each change. The sections that follow — reasoning routes, keeping Grounding fresh, Reasoning Fuel — are refinements to grow into once the basics answer well; they are not needed on day one.

Give the Assistant a Route, Not Just Rules

The Assistant doesn't have to answer from a single lookup. Depending on the model and the Reasoning setting (see Choose a Model and Reasoning Effort), it can look something up in the Knowledge Base, think about what it found, and look again — several times if needed — before answering.

You can put that to work: Instructions can describe the route to a good answer, not just the rules for giving one. For example:

To answer a question about changing how something looks on the page: first identify the element, then find the setting or variable that controls it, and name where that setting lives.

Each step tells the Assistant what to look up next, with one lookup guiding the following one. Three things to keep in mind:

• Routes need Reasoning. With Reasoning Off, expect a single lookup — keep to one-step answers. Multi-step routes work best at Medium or High, and every extra step adds a little time and cost.

• Always give the short way out. Say what to do when a step comes up empty — for example, "if you cannot confirm the exact name, say what is uncertain and give the general approach." That keeps answers graceful when the route can't finish.

• Test the route. Add a question or two to your question list that can only be answered by following the whole route, and judge the final answer — does it name the right things? In the Preview tab, the Assistant's "thinking" text often shows the route being followed, which is the quickest way to see where a route goes wrong.

Keep Grounding Fresh — It Is Where Links Come From

Grounding Knowledge is generated for you: each build of your Reverb 2.0 target writes a knowledge-*.zip archive that mirrors your published pages (see Generate the Target). Because those files carry Landmark IDs — anchors created from the IDs in your source documents — the Assistant's answers can link readers to the exact page and section.

• Re-upload after every republish. The Assistant answers from what you uploaded, not from your live site. If you publish new content but skip the upload, answers lag behind your help.

• Give your topics stable IDs. Landmark IDs come from your source documents. Topics and major headings with their own IDs produce links that land readers on the right section, not just the right page.

• Check the links. Ask the Assistant something your help clearly covers, and click the source link under the answer. It should open the correct published page. A right answer with a missing or wrong link means the Assistant is not drawing on your published content for that topic — usually a sign the archive is stale or the topic is not in your published output.

Add Reasoning Fuel Carefully

Reasoning Fuel is your private expertise: troubleshooting notes, internal references, "why it works this way" background — uploaded to the same Knowledge Base but never published and never linked (see Add Reasoning Fuel). A few rules keep it an asset instead of a liability:

• Facts only, stated plainly. Short sections, each one self-contained: a name, its value or location, what it does. Clean Markdown files retrieve best.

• Keep a fact and its context together. The Assistant reads your files in passages, not cover to cover. A statement that only makes sense next to a paragraph three pages earlier can arrive without it — repeat the context.

• Accuracy is everything. The Assistant treats your files as truth and repeats errors confidently. Review fuel files like you review published content.

• Name files well and prefix them. File names are for managing your Knowledge Base, not for readers. A shared prefix such as aux- keeps your files together in the Uploaded list, and descriptive names make it easy to tell — in the Preview tab and months later — which file holds which facts.

• Update or remove, don't accumulate. Outdated files are found by lookups just as easily as current ones. When a product change makes a file wrong, replace it.

Test with a Question List

Do not judge changes by asking whatever comes to mind. Build a short, fixed question list once, and re-run it after every change — same wording every time.

1. Write 10–15 real questions your users would ask, with the answers you expect — including the exact setting or feature names, and (for questions your help covers) the page the answer should link to.

2. Add 2–3 questions from other subjects the Assistant already handles well. These make sure a change didn't break something unrelated.

3. Add 2–3 trick questions about things that don't exist — an invented setting name, a feature your product doesn't have. The right answer is "I'm not sure" or a correction, never confident detail.

4. Ask each question in a fresh Preview chat on the Platform (one question per chat — earlier questions influence later answers in the same conversation).

5. Compare before and after. Testing whether new fuel files help? Run the list once without them and once with them. Keep a simple scoresheet: right lever, right names, right steps, right link.

After you change the Knowledge Base, the Assistant briefly shows an indexing state while it takes in the new files — it keeps answering from the previous set until then. Wait for indexing to finish before you test.

Watch for Made-Up Answers

AI models can hallucinate — state invented specifics with full confidence. For a documentation assistant this is the failure that matters most, and your question list is the net that catches it:

• An invented name is a hard failure. If the Assistant names a setting, variable, or menu item that doesn't exist — even once — treat it as a bug in your setup, not bad luck.

• The trick questions are your alarm. A healthy Assistant hedges or corrects; a hallucinating one elaborates.

• The fix is the missing fact, not scolding. When the Assistant invents an answer, it usually "knows" a plausible-but-wrong one. Add the true fact to your Reasoning Fuel where a lookup will find it — and if it keeps slipping through, put that one fact in the Instructions.

Keep It Healthy

• Every publish: upload the new knowledge-*.zip (with per-parcel archives, just the parcels that changed).

• Every product release: re-read your Reasoning Fuel for facts the release changed; update or remove stale files.

• Every change: re-run the question list. It takes minutes and catches regressions while they are still easy to trace.

• Model and Reasoning settings: test changes against your question list too, and keep the least expensive configuration that passes — see Choose a Model and Reasoning Effort. A well-structured Knowledge Base usually beats a bigger model.