--- title: "How to write product documentation that AI assistants read and cite correctly" description: "AI assistants answer from your help center now. Here's how to structure articles and steps so ChatGPT and support bots quote them correctly." url: "https://www.clueso.io/blog/write-documentation-for-ai-assistants" updated: "2026-11-05T12:01:44.750Z" --- # How to write product documentation that AI assistants read and cite correctly AI assistants answer from your help center now. Here's how to structure articles and steps so ChatGPT and support bots quote them correctly. - AI assistants retrieve sections, not pages. Anthropic describes the pieces as "usually no more than a few hundred tokens," so each section has to name its own subject and conditions. - Write every step so it works without its screenshot: the on-screen label, where it sits, and what happens after the click. - Check that assistants can reach your articles. Sites that opt out of OAI-SearchBot don't appear in ChatGPT search answers, and Vercel found that the major AI crawlers, apart from Google's and Apple's, don't run JavaScript. - Keep one live version of each instruction. An assistant quotes a retired step as fluently as a current one. - Google says AI search needs no special optimization, and Google's John Mueller wrote in June 2025 that no AI system uses llms.txt. Fix the articles first. ## Introduction Your help center has a new first reader. Before a customer opens one of your articles, an assistant may already have read it for them, whether that's ChatGPT answering a how-to question or the support bot on your own site. The customer gets a paragraph assembled from a few sections of your page, presented as your answer, and never sees the rest. That works when the section the assistant picked is complete and current. When it isn't, the company pays for it. In November 2022, after their grandmother died, Jake Moffatt asked the chatbot on Air Canada's website about bereavement fares. The chatbot told them they could book now and submit the ticket for the reduced rate within 90 days. Air Canada's own "Bereavement travel" page, linked from that same answer, said the policy didn't cover requests made after travel. Air Canada refused the refund and argued before British Columbia's Civil Resolution Tribunal that the correct information was on its website all along. In February 2024 the tribunal [ordered the airline to pay $812.02](https://decisions.civilresolutionbc.ca/crt/crtd/en/525448/1/document.do), and its reasoning applies to anyone whose documentation feeds an assistant: "There is no reason why Mr. Moffatt should know that one section of Air Canada's webpage is accurate, and another is not." Customers treat the assistant's answer as yours. This guide covers how assistants pull answers out of documentation, how to write sections and steps that stay correct when they're lifted out of the page, and how to stop an assistant from finding the wrong version. ## What changes when an AI assistant reads your documentation? ## What changes when an AI assistant reads your documentation? Writing documentation for AI assistants means structuring each help article so a retrieval system can lift any single section out of the page and still give a correct, complete answer. Every section names its own subject, every step names the on-screen element it refers to, and only one current version of each instruction is live. Assistants that answer from documentation work the same way underneath. They split pages into small pieces, find the pieces closest to the question, and write an answer from those. Anthropic, describing its own [retrieval research](https://www.anthropic.com/news/contextual-retrieval), says the pieces are "usually no more than a few hundred tokens," which is a few paragraphs of a typical help article. The trouble is what a piece loses when it's cut out. Anthropic's example is a chunk that reads "The company's revenue grew by 3% over the previous quarter." On its own, it doesn't say which company or which quarter, and help articles break the same way. "Open the settings panel and turn this on" was clear under a heading three paragraphs up, but lifted out of the page it no longer says which setting, or who's allowed to change it. When Anthropic added that missing context to each chunk before indexing, retrieval failures fell by 49%, and by 67% with reranking added. You can't change how ChatGPT or your support bot vendor splits your pages, but you can write each section so it carries its own context. ## How do you structure a help article so each section stands on its own? ## How do you structure a help article so each section stands on its own? Start with the heading. An assistant matching a question like "how do I export a report as a PDF" looks for text that says that. A heading that names the task in the customer's words, such as "Export a report as a PDF", gives it something to match. "Overview" and "More options" give it nothing. Then make each section repeat what a reader would otherwise pick up from the surrounding page. Name the feature instead of writing "this setting," and name the screen instead of "the panel above." When a step only works for some customers, say so inside the section that needs it rather than in a note at the top of the article: "Only workspace admins see the Billing tab." An assistant that pulls the steps without the note will otherwise send every user looking for a tab half of them don't have. Keep one task per article where you can. A long article covering setup and billing gets split anyway, and the pieces lose the thread that connected them. Separate articles give each job its own heading and its own URL for an assistant to cite. [How a knowledge base is organized](https://www.clueso.io/blog/what-is-a-knowledge-base) covers the structure above the article level. ## How should you write steps so they still work without the screenshot? ## How should you write steps so they still work without the screenshot? When an assistant turns your article into a paragraph of text, the screenshots stay behind. A step that leans on the image, like "Click the button shown below," becomes an instruction to click nothing in particular. A step that survives on its own text names the on-screen label and where it sits, then says what happens after the click: "Click **Export** in the top-right corner of the report. The export dialog opens with PDF selected." The reader looking at the screenshot loses nothing, and the reader getting it secondhand from an assistant can still follow it. Alt text helps for the same reason. A screenshot described as "Export dialog with PDF and CSV options, PDF selected" carries its information to any reader that can't see the image, including a crawler, and screen-reader users get the same benefit. Writing every step this way by hand is slow, because each click gets described twice: once in the screenshot and again in words. Clueso's [step-by-step help articles](https://www.clueso.io/features/help-articles) generate both from a screen recording, so each click becomes a written step with a zoomed-in screenshot placed at that step, on every plan. What's left for you is checking that the step text uses the exact labels your customers see. You can then publish the article to a Clueso help center or copy it as Markdown or HTML into the help center you already run. ## Can AI assistants reach your help center at all? ## Can AI assistants reach your help center at all? None of this matters if the assistant never gets the page, and two settings can block it. The first is robots.txt. OpenAI runs [separate crawlers for separate jobs](https://developers.openai.com/api/docs/bots), and its documentation says "sites that are opted out of OAI-SearchBot will not be shown in ChatGPT search answers." GPTBot, which collects content that may be used for training, is a different user agent. If your security or legal team blocked OpenAI's crawlers wholesale, check which ones they blocked, because opting out of training doesn't require opting out of search. The second is JavaScript. In December 2024, Vercel [analyzed AI crawler traffic across its network](https://vercel.com/blog/the-rise-of-the-ai-crawler) and found that "none of the major AI crawlers currently render JavaScript." The exceptions were Gemini, which uses Googlebot's infrastructure, and AppleBot. A help center that loads article text with client-side JavaScript can look empty to ChatGPT and Claude while looking fine in your browser. To check, open an article with "view source" or a plain curl request and search the raw HTML for a sentence from the steps. Articles behind a customer login can't be cited by a public assistant at all. That's right for internal SOPs, and usually wrong for the how-to articles customers search for. ## How do stale docs turn into confidently wrong AI answers? ## How do stale docs turn into confidently wrong AI answers? A person reading a stale article often notices something is off, because the screenshot shows an old layout or the menu isn't where the article says. An assistant reports the old instruction in the same confident tone as a current one, and the customer has no screenshot to compare against. Watch for two forms of it. The first is a retired step nobody removed: the feature moved, and the article still describes where it used to be. The second is duplication: when a "legacy" article and its replacement both stay live, retrieval can pick either one, depending on which happens to match the wording of the question. That's the Air Canada problem at a smaller scale, with two sources disagreeing and a customer who has no way to know which is right. Keep one live article per task. When a feature changes, edit the canonical article and redirect or unpublish the old one instead of leaving it up for customers on the previous version. If you genuinely support two versions, put the version in the heading and in the first line of each section, so a lifted section still says which product it describes. Google's [guidance on AI search](https://developers.google.com/search/blog/2025/05/succeeding-in-ai-search) adds one more check: everything in your structured data should also be visible on the page, so FAQ schema that says something the article doesn't is a second, conflicting version of your docs. Finding the stale steps is the expensive part, since nobody rereads 200 articles after every release. Clueso's [Auto Updates](https://www.clueso.io/features/auto-updates) re-runs an existing guide against your current product and regenerates what changed, rewriting the step-by-step article and the video together. With GitHub connected, a code push flags every video it made out of date, so you know which guides to run. Auto Updates is a paid add-on to the Enterprise plan. For the rest of that process, [how to automatically update help center articles](https://www.clueso.io/blog/how-to-automatically-update-help-center-articles) covers detection and regeneration in detail. ## Do llms.txt files or other AI optimizations help? ## Do llms.txt files or other AI optimizations help? Less than the attention around them suggests. [llms.txt](https://llmstxt.org/) is a proposal Jeremy Howard published in September 2024: a Markdown file at your site root that lists your key pages for AI agents, plus clean Markdown versions of those pages. It costs little to publish. But Google's John Mueller [wrote in June 2025](https://www.seroundtable.com/google-ai-llms-txt-39607.html) that "no AI system currently uses llms.txt," and Google's May 2025 guidance on AI Overviews and AI Mode says that what it "has long advised carries across to these new experiences." Publish an llms.txt file if your docs platform generates one for you. Don't expect it to rescue articles that fail the checks in the next section. ## How do you check whether an assistant gets your article right? ## How do you check whether an assistant gets your article right? Pick a question one of your articles answers, phrase it the way a customer would, and ask ChatGPT with search turned on, then ask your own support bot. Read each answer against the article. Then copy a single section out on its own, paste it into an assistant with no other context, and ask it to explain the steps. If it has to guess the product or the setting, the section needs more context. After those two tests, run the article against this list: - The heading names the task in the customer's words. - Each section names the feature and the screen instead of pointing back up the page. - Plan and role conditions sit inside the section they apply to. - Every step gives the on-screen label and its location, then the result of the click. - Screenshots have alt text that describes what they show. - The article text is in the raw HTML and isn't blocked by robots.txt or a login. - Only one live article covers the task, and its structured data matches the visible text. ## Frequently asked questions ## Frequently asked questions ### Do I need an llms.txt file for my documentation? It's optional: the proposal asks for a Markdown index of your key pages plus Markdown versions of each page, and Google's John Mueller wrote in June 2025 that no AI system currently uses it. If your docs platform creates one automatically, keep it. If it doesn't, the time is better spent on the articles themselves. Clueso lets you copy any help article as Markdown or HTML, so a clean Markdown version of a page takes one click. ### How do I optimize help center content for ChatGPT? Make it reachable first. Check that robots.txt allows OAI-SearchBot, since OpenAI leaves opted-out sites out of ChatGPT search answers, and that the article text is in the page's HTML rather than loaded by JavaScript. Then write headings that name the task, write steps that name the on-screen label and the result, and keep one live article per task. ### Should I block GPTBot? That's a training decision, and it's separate from search. OpenAI uses GPTBot to collect content that may train its models, and OAI-SearchBot to surface sites in ChatGPT search. You can block the first and allow the second, so your docs stay citable without being used for training. ### Does an AI support bot need different documentation from the public help center? When a support bot answers from your help center, the same rules apply, and the bot repeats a stale article to every customer who asks. Keeping the source current matters more than writing separate content for the bot. Clueso's [Auto Updates](https://www.clueso.io/features/auto-updates), a paid add-on to the Enterprise plan, regenerates guides when your product changes, so the articles a bot reads keep matching the product. ## Which article should you fix first? ## Which article should you fix first? Start with the article behind your most common support question, since that's the topic assistants are most likely to be asked about. Ask ChatGPT that question today and compare its answer with the article, line by line. Whatever it gets wrong is your first edit.