How to write a help file your support chatbot can use

A practical guide to the Markdown help file format a Cerberius Agents chatbot reads, and how to keep it accurate so answers stay right.

A chatbot is only as good as what it has read. If your docs are thin, out of date or hidden behind a site it can't read, it will give thin, stale or empty answers. This is one of the few parts of AI support you fully control.

This article covers how a Cerberius Agents chatbot learns from your docs, the Markdown help file format, and a few habits that keep the content accurate.

What the chatbot answers from

In Cerberius Agents, a chatbot answers only from its help sources. It can't see your code, databases, logs or anyone's account. It also can't answer anyone until at least one source has been read.

There is no approval step either. Chatbot answers go to the visitor straight away. So the quality of the source is the quality control. (Your support agent, which works through the Queue, is a different thing: it answers your team, and a person approves its replies unless you turn on automatic replies.)

You can add up to 10 sources per chatbot. You find them under Platform › Settings › Chatbots, then open a chatbot and go to Help sources. Each source is one of two types:

Why a single-page help site can be a problem

Many modern help centres are built in the browser. The page loads as an empty shell and the text appears after scripts run. A human sees a full page. A reader that only looks at the page's HTML sees almost nothing.

Cerberius Agents' own documentation for chatbots says a help website only works if the pages have their text in the HTML, and that single-page apps show no text to a reader. Its advice is to use a help file instead.

You can check this yourself. Open one of your help pages, view the page source, and search for a sentence from the article. If you can't find it, a reader that doesn't run scripts won't find it either.

Other things a help website source skips:

Also, a website source reads up to 400 pages. If your docs are bigger than that, split them across sources or use a help file for the important material.

If your site is readable, a website source is fine. End a folder address with a slash. https://example.com/help/ reads the help folder. https://example.com/help with no slash is treated as a page in the top folder, so the whole site is read, blog included. If your help centre has its own address, such as https://help.example.com, the slash doesn't matter.

The help file format

A help file is one public Markdown (.md, .markdown) or text (.txt) file. Many sites already publish one for AI tools, often called llms-full.txt. If you have one, check it before writing anything new.

The rules are short:

Here is a small example:

# Changing a booking
URL: https://example.com/help/bookings/change
Open the booking and click Edit.
## Moving it to another day
Pick the new date and save.

# Cancelling a booking
URL: https://example.com/help/bookings/cancel
Open the booking and click Cancel booking.

Practical limits on the file

The address must end in .md, .markdown or .txt. The file must be public and under 2 MB. If the address returns a web page instead, such as your site's "page not found" screen, it's refused. That last one catches people who mistype the address or move the file.

Writing pages the chatbot can use

The format is only the container. The writing is what matters. These are general habits, not product rules.

One question per page

A page titled "Changing a booking" is easy to match to a question. A page titled "Bookings, payments, and other things" is not. Since each # heading starts a page, make the title say what the page helps with.

Always include the URL line

Without it, the chatbot has nowhere to point. With it, the answer can link visitors to the full page. Use the real public address, and check that it still works.

Use sections for variations

Use ## headings for the cases within a task: "Moving it to another day", "Changing the number of guests". Name the sections in the words customers use, not your internal feature names.

Write the exact steps

Name the button, the screen and the field as people see them. "Open the booking and click Edit" is better than "modify the reservation". Say what happens afterwards if it isn't obvious.

Don't write what you can't stand behind

The chatbot answers only from what it read, so every sentence is something it may repeat to a customer. Avoid vague promises such as "usually instant" unless you mean them. Leave out plans and half-built features. If something is changing, say so in the page.

Keeping it accurate

Accuracy slips quietly. A button gets renamed, a plan changes, and the docs say the old thing.

Cerberius Agents' chatbot documentation says sources are read again every night, and whenever you click Read again. So after you fix a page, you don't have to wait for the night run. Click Read again on the source and ask the chatbot the question that exposed the problem.

A routine that works for a small team:

  1. When a wrong answer turns up, find the page it came from. Fix that page, not just the symptom.
  2. When a release changes a screen or a setting, update the help file in the same piece of work.
  3. Once in a while, ask the chatbot five real questions from recent tickets and compare the answers with your docs.
  4. If customers keep asking something the docs never covered, add a page.

The chatbot's own documentation also points to Metrics and feedback for seeing how things are going. See Metrics and feedback for what is shown.

Where to go next

Full details of both source types are on the Help sources page. If you haven't made a chatbot yet, start with Creating a chatbot.

All articles

Loading…