How to set up an AI chatbot for documentation

An AI chatbot for documentation answers your customers from your docs, so they get the answer without hunting for the page. Setting one up well takes an afternoon. Choose the pages it learns from, add what your docs leave out, test it on questions customers actually sent you, and refresh it each time you ship. How well it answers depends more on those four steps than on which tool you pick.

Deacon is an AI customer support agent built for founders who answer support themselves. It answers your customers in seconds from your documentation, says so when the docs don’t cover a question, and shows you what people got stuck on. There’s a free plan, and it needs no card.

Choose the pages it learns from

A chatbot treats every page you give it as true, so the first job is leaving the wrong ones out. Crawl your docs site, then go through the list of pages it found and take out the ones that don’t belong.

Keep the pages that answer customer questions. That’s your help articles and how-tos, your getting-started guide, your pricing page, your limits and your policies on refunds and cancellations.

Leave out anything you wouldn’t want read to a customer as fact.

• Release notes and changelogs, which describe how things used to work.
• Docs for old versions, unless customers still run them.
• Blog posts, launch announcements and case studies, which were written to sell rather than to answer.
• Your careers page, and your terms and privacy policy unless customers ask about them.
• Translated copies of the same page. A good chatbot answers in the reader’s language from one version, and two copies can drift apart.

Generated API reference is a judgement call. It’s long and repetitive, but it’s often the only place an endpoint or an error code is written down, so include it if customers ask about your API.

Add what your docs leave out

Customers ask about things nobody wrote down, such as what happens when a card fails, whether a plan can be paused or how long a refund takes. Write each one down as a short answer before launch. Without it, a careful chatbot can only say it doesn’t know. Each kind of source has its place.

• A web page is the best source, because an answer taken from it can link to it. Short answers can go on an FAQ page.
• A PDF or Word file suits docs that aren’t public, such as an onboarding guide for customers. Find out how the tool reads PDFs. One that reads each page as an image copes with scans and tables, and one that only pulls out the text layer gets nothing from a scan.
• Pasted text is the quickest way in for an FAQ that lives in an email or a shared doc.
• A written question and answer is the most exact, for the answers only you know.

Put every fact in words, not in a screenshot. Many chatbots skip the images on a web page, so a picture of your settings screen or a pricing table saved as an image teaches them nothing.

What happens to your docs inside the chatbot

Nearly every documentation chatbot works the same way, by a method called retrieval-augmented generation. It cuts your docs into passages, finds the few closest to each question and has a language model write the answer from those, and a well-built one says it doesn’t know when they don’t cover the question. Grounding AI takes the method a step at a time.

Three writing habits follow from that.

• Give each topic its own heading, in the words customers use. A passage is only as easy to find as the heading above it and the words inside it.
• Write error codes, setting names and menu paths as text. Keyword search can only match words it can see.
• Keep a fact next to the thing it’s about. “This costs extra” means nothing once it has been cut away from the heading that says what “this” is.

How to write knowledge base articles goes further, with before-and-after examples.

Test it with questions customers really sent

Before any customer sees it, run it against real questions. Take 20 or 30 from your inbox or your chat history, in the customers’ own words, and ask each one in the tool’s test mode. Sort what comes back into three piles.

• Right answers. Nothing to do, unless the link under one opens the wrong page.
• Wrong answers. These usually mean a page is out of date or two pages disagree. Fix the page, not the chatbot.
• “I don’t know”. If your docs really don’t cover it, that’s the right reply, and you’ve found a page to write. If they do, the page either wasn’t included or words it differently from your customers.

Then try the questions it should refuse. What to look for in a documentation AI assistant has six tests for that, and they take ten minutes.

Keep it current after every release

A chatbot answers from the docs it last read, so a release that moves a button can make its answers wrong overnight. Some tools re-read your site on a schedule and some wait for you. Either way, make it part of shipping.

• List the pages a release touches, and update them before it goes out.
• Refresh those pages in the chatbot on the day you ship.
• Look through your written answers for anything the release changed, because many tools prefer them over your pages when the two disagree.
• Read the first day’s conversations after a big release. Questions about the new feature show you what the docs left out.

How Deacon answers from your documentation

Deacon turns your docs into answers with no flows or decision trees to build. It starts from your home page and the pages visitors ask about first, such as pricing and help, and you add any other page by its link. It answers your customers in seconds, at any hour, in the language they write in.

It learns from four kinds of source, your website, uploaded files, pasted text and answers you write. Here’s when each one starts answering, and whether an answer taken from it can link back.

When you sign up, Deacon reads your home page and up to four pages it links to that visitors ask about first. Those are your pricing page, your help or FAQ, the page on what your product does and your contact or about page. It never takes blog posts, news, careers pages or customer stories this way, nor sign-in or account pages. On a paid plan with pages to spare, Add website crawls the whole site, up to a hundred pages a crawl, and lists every page unticked. Translated sections such as /fr/ are skipped when your pages name them in hreflang tags, and the crawl says which it skipped. Without those tags they’re kept, and the ones that look like translations are pointed out, so you can leave them out. The whole folders or single pages you tick there wait for Retrain agent.

Each page shows how much text Deacon took from it, so one that came back nearly empty stands out before you rely on it. A page that would take you past your plan’s knowledge limit is marked over limit rather than dropped without a word, and it’s tried again at the next retrain. Retrain agent never fetches anything, so pressing it spends none of the month’s pages. Any page Deacon hasn’t read can be added one at a time by its address.

Edits wait for Retrain agent too, except an answer you change from its conversation, which is read again straight away. Nothing is re-fetched on a schedule, so re-fetch a page by hand when it changes.

Try it in the Playground before your customers see it. It’s the real widget, you can set who the visitor is, such as their plan, and its chats are never counted against your answers.

For every question, Deacon searches your docs by meaning and by keyword and answers from the few passages that fit best. Grounding AI shows each step, from how a page is cut up to how many passages reach the model and the rules it answers under. When your docs don’t cover the question, Deacon says it doesn’t know instead of guessing, and asks for the visitor’s email. If they leave it or ask for a person, the owners on your team get an email.

Deacon also shows you where your docs fall short. Every question your docs didn’t cover waits in Conversations with an Answer this button. Write the answer once and press Save & check. Deacon shows you the reply it now gives and how many other open questions your answer covers. Your answer becomes part of what Deacon knows, so the more you answer, the less it needs you. Topics group what people ask, count the people behind each group and label most of them, so you see what customers are stuck on and what they want next.

Knowledge is counted by the text Deacon takes from your docs, not by file size, and a page of docs comes to about 15,000 bytes. So the free plan holds about 67 pages, Starter about 1,000 and Growth about 3,330. Every feature is on every plan, and the free plan needs no card and has no end date. How a knowledge base chatbot works in Deacon shows the same steps on the dashboard’s own screens, and the pricing page has the plans.

Questions about AI chatbots for documentation

How long does it take to set up?

The script takes a few minutes, and Deacon learns from your home page straight away and from the pages visitors ask about first as they arrive, so it can answer within a minute or so. Checking the pages it picked and testing on real questions is the part worth an afternoon.

What if my docs aren’t public?

Upload them as PDF, Word, Markdown, text, CSV or HTML files of up to 10 MB each, or paste the text in. Deacon reads a PDF’s pages as images, so a scan works too. A PDF of up to 200 pages is read in full, and a longer one is turned away with a note to split it into parts. An answer from a file carries no link.

Can I add Deacon to docs hosted on GitBook?

Not on the GitBook site itself, because GitBook’s integration docs say integrations that inject JavaScript into a site aren’t possible. Deacon can still learn from your GitBook pages as a website, read like any other, and answer your customers on your own site or inside your app.

Does Deacon keep up when my docs change?

Only when you tell it to. Nothing is re-fetched on a schedule. After a release, open your site in Knowledge Sources, re-fetch each page that changed and press Retrain agent. The old version keeps answering until you do, so customers never get half an update.

Why does it say it doesn’t know when my docs cover the question?

Usually for one of three reasons. The page wasn’t ticked, or hasn’t been retrained since. The answer is only in an image, and Deacon skips images on a web page. Or the page words it differently from your customers, so put their words in a heading. The quickest fix is Answer this on the question itself, and Save & check shows you whether Deacon now gives your answer. A question about the visitor’s own account is different, because Deacon can’t see accounts and always declines those.