How to Write Documentation for Humans and AI: A Practical Guide

Key takeaways

• AI does not read your help center top to bottom. It splits articles into chunks and retrieves a few in isolation, so any section leaning on context from elsewhere breaks

• The highest-impact fix is making each section stand alone: restate the product, the location and the prerequisite inside the section instead of relying on the introduction

• Writing for AI and writing for humans is the same project. Descriptive headings, consistent terms, short sentences and question-style FAQs help both readers at once

• The delivery layer is where most teams lose ground. Serve clean Markdown, keep content out of JavaScript-only rendering, and treat llms.txt as a bonus rather than a fix

• None of it survives a stale article, because retrieval cannot tell that your product changed

To write documentation for both humans and AI, make every section stand on its own: give it a descriptive, question-style heading, restate the product and prerequisites inside the section rather than in the introduction, keep one topic per section, and use the same name for a feature everywhere it appears. The same changes that make a page retrievable for an AI system make it faster to skim for a person.

Most knowledge bases were built for one reader: a human who skims, backtracks, infers meaning from context, and reads the introduction before diving into step four.

AI does none of that. Support chatbots, AI search tools, and LLM-powered copilots pull from the same knowledge bases your human customers use, and they consume that content differently. This guide covers what to change, why it matters, and how to check whether it worked.

Why documentation quality matters more when AI is involved

Bad documentation costs more when AI reads it, because AI removes the recovery step.

A customer who hits an outdated help article has options. They can raise a ticket, search again, or find another article. Frustrating, but recoverable. Your chatbot has no such instincts: it takes the content at face value, cites it, and presents it as correct, with no way to know it is wrong. The customer gets a specific, incorrect answer and often acts on it. Most hallucinations blamed on the model start here, in a gap or a contradiction the documentation left open. More on that failure mode in most wrong AI support answers are a stale doc in a confident voice.

Writing documentation that works well for AI also makes it better for humans, which is why this is one of the rare content projects with no tradeoff in it.

How do humans and AI read documentation differently?

Humans read across a page and fill in what is missing. AI systems read a few isolated pieces of a page and cannot fill in anything.

Every fix on the AI side also helps the person who landed mid-article from a search result, because they did not start at the top either.

How AI actually reads your knowledge base

The pattern behind almost every documentation chatbot is called RAG, short for Retrieval-Augmented Generation, and knowing how it works changes what you write. Your knowledge base gets split into chunks of a few paragraphs and stored in a searchable database. When a customer asks something, the system retrieves the chunks most semantically similar to the question, and a large language model writes an answer using those chunks as its only context.

Chunking exists because a model cannot hold your whole knowledge base in its context window at once, and a narrow, focused context produces better answers than a broad one. Four consequences follow:

• Sections are read in isolation. A section that leans on something earlier in the article loses that context entirely

• Implicit information does not exist. If you did not write it, the AI does not know it

• Chunk boundaries are unpredictable, so two related facts sitting far apart on the page can land in separate chunks and never be retrieved together, which is why proximity on the page matters more than it used to

• Retrieval runs on semantic similarity, so wording that does not match how customers phrase their questions keeps the right content buried

kapa.ai's writing guide describes the same mechanics from the retrieval side, and AWS's documentation best practices for RAG applications lands on the same conclusion: break large documents into smaller, self-contained units.

Structure: the foundation of AI-ready documentation

Use descriptive, question-style headings

Write headings the way customers would type the question into a search bar.

For humans, headings are navigation. For AI they are signals about what a section contains and how relevant it is to a query. When a user asks "How do I reset my password?" and your heading reads "Account Management," nothing marks that section as relevant. "How to Reset Your Password" matches immediately.

Three common heading habits that break retrieval:

• Vague ones: "Overview," "Getting Started," "Additional Information"

• Time-sensitive ones like "New Feature" or "What's New," since retrieval systems are not time-aware

• Duplicates across articles. Two guides both titled "How to Set Up the Integration" give retrieval no way to tell them apart, and whichever one scores marginally higher becomes the answer to every integration question. Name one for Slack and the other for Zapier

Test each replacement in one move: if someone typed this heading into a search bar, would it match what the section actually contains? Carry product and feature names in it, especially for sub-features that turn up in several contexts.

Keep one topic per section

When a section covers several topics at once, retrieval dilutes and the answer degrades. A section called "Settings" covering password changes, billing updates, team permissions, and two-factor authentication is four topics crammed into one. Retrieve that chunk to answer a two-factor question and the response comes back noisy at best, wrong at worst.

Split any section covering more than one distinct task. This does not mean shorter articles. A well-structured 2,500-word article with clearly defined sections outperforms a 600-word one covering four topics under vague headings, and a clean H1 to H2 to H3 hierarchy means even an isolated chunk carries information about where it sits.

Writing: how to make every section retrievable and accurate

Make every section self-contained

This is the single most impactful change you can make to improve AI response quality, and most documentation gets it wrong.

Documentation typically assumes linear reading: the introduction sets context and later sections build on it. A chunk pulled from the middle has no introduction, only whatever is written in those few paragraphs. So an article that opens with "This guide assumes you have already created your account" and later says "Navigate to the dashboard and click Configure" gives the AI no idea what dashboard, what product, or what configuration.

Before: "Navigate to settings and click the toggle to enable it."

After: "In the Pageloop dashboard, go to Settings > Notifications and click the toggle to enable email alerts."

The second version works as a standalone chunk, and the first does not. The same applies to prerequisites: state them inside the section that needs them rather than in an introduction the reader may never reach. And keep a constraint next to the thing it constrains, so if an API token expires after 24 hours, that belongs in the same paragraph as the login steps. Proximity is the whole principle here, because chunk boundaries are unpredictable and the closer two related facts sit, the more likely they survive the split together.

Use consistent terminology throughout

Inconsistent naming is one of the most common and least visible causes of poor AI retrieval.

If your product has a feature you call "Workspaces" in the getting started guide, "Projects" in the API reference, and "Environments" in the troubleshooting FAQ, AI will not connect these. When a user asks "How do I create a Workspace?", retrieval searches for content matching "Workspace." It finds the getting started guide and misses everything else, because the other articles never contain the word. AI systems have no prior associations for product-specific names, which makes consistent usage the only thing connecting a query to the right content.

Agree on one name per feature, concept, and action, and write those names into a shared list. Twenty to thirty core terms covers most products. If your tooling supports it, encode this rather than relying on memory: Pageloop takes a configurable style guide and a list of product-specific terms in AI settings, so generated drafts follow your naming instead of inventing a synonym.

Replace vague pronouns with specific names

Vague pronouns are natural in conversation, and in documentation they create real problems once content is retrieved in isolation. Take a sentence like this one:

After configuring the integration, test it to make sure it is working correctly.

A human reading the full article works out whether "it" means the integration or the configuration. AI working from a retrieved chunk has no surrounding paragraphs to work from. Rewrite it as "Once the Slack integration is connected, you can adjust the notification settings in the Integrations panel," and apply the same treatment to every "it," "this," "that," and "the following" whose referent is not obvious from the chunk alone.

Long sentences fail the same way, and so does passive voice, which hides who performs the action. When one sentence carries several conditions, AI has to work out which part answers the question. Split "If you are on the Pro plan and have connected your calendar, you can enable sync by going to Settings, then Integrations, then clicking Enable" into two: the requirement, then the steps. One idea per sentence, and any single one of them survives retrieval on its own.

Formatting: what helps AI and what hurts it

Five formatting habits break AI processing while looking fine to a human:

• Symbols in tables. Checkmarks and crosses get misread or dropped when a table is flattened into text, and a cross can flip into a positive. Use "Yes" and "No." Fill every empty cell too, since AI cannot tell whether a blank means not applicable, not available, or nobody filled it in. Keep tables short and grouped by category, because the relationships between headers and values break down across a wide one

• Images carrying information no text repeats. AI cannot see a screenshot. Add alt text describing what it shows, and where an image carries a process, describe that process in text as well

• Content locked in formats that are not machine-readable. PDFs, a Loom walkthrough, or a JavaScript-rendered widget are difficult or impossible for retrieval systems to parse. Keep content in plain HTML or Markdown on the page, and use semantic HTML properly: real heading, list, and table markup rather than heading tags picked for how they look

• Unfenced code. AI systems confuse code for prose. Put examples in fenced code blocks with the language labelled, so the model knows where an example starts and ends

• "Click here" link text, which tells an AI system nothing about the destination

Content strategy: what to add to every article

Add a FAQ section to every article

FAQ sections at the end of individual articles are one of the most underused improvements for AI accuracy.

They work because of how retrieval matches. It compares the query against your content, and customers phrase queries as questions. A paragraph containing the answer to "Can I connect Slack to multiple workspaces?" ranks lower than a FAQ entry asking exactly that and answering it directly.

Source the questions from your support inbox rather than from the article, because the ones your article did not anticipate are exactly where your chatbot struggles. Coverage gaps in your chatbot logs, meaning the questions that returned a low-confidence answer or none at all, work just as well. Attach three to eight per article, all on that article's topic, since one giant FAQ page chunks poorly and returns irrelevant answers.

Include exact error messages in troubleshooting articles

Customers who hit an error usually search by pasting the exact message, so documentation carrying that text alongside the fix matches directly. Generic troubleshooting like "If you have connection issues, check your network settings" will never match a query containing a specific error string:

Error: "Authentication failed (401)" This error occurs when your API credentials are expired or invalid. To resolve it: [steps]

Metadata: the layer that powers AI retrieval

Metadata is what AI retrieval systems use to assess relevance before they read the body of an article. On most documentation platforms it lives in YAML frontmatter at the top of each file, and it is the cheapest part of your information architecture to fix.

• Descriptive title carrying the feature name and the action, so "Getting Started with Workspace Setup" rather than "Getting Started"

• Meta description: one or two sentences on exactly what the page covers

• Tags and categories, so retrieval returns the right cluster

• Last updated date. Retrieval systems increasingly weight recency, and human readers use it to decide whether to trust the page at all. This is also the field most help centers leave to whatever the platform sets automatically, which means a typo fix can reset it and a genuine rewrite can leave it untouched

• Version or plan tags, so AI returns the right answer to the right customer

URL structure is another signal. /docs/setup-slack-integration tells retrieval about the content before it reads a word. /docs/page-1234 does not.

Delivery: making your docs easy for AI to fetch

Everything above assumes the AI can reach your content at all. Getting the text in front of the system is a separate problem, and most teams skip it entirely.

Format decides most of it. Clean Markdown parses far more reliably than a PDF, whose visual layout scrambles machine reading, and it is much cheaper to process: the same page served as HTML carries navigation, styling and markup that can eat most of the tokens an agent spends reading it. Coding agents like Cursor, GitHub Copilot and Claude fetch documentation live during a session, and the ones handed raw Markdown fit a whole page into context where the HTML version arrives truncated. Documentation platforms increasingly solve this with content negotiation, serving Markdown to agents and HTML to browsers from one source.

Rendering decides the rest, since pages that assemble content through JavaScript can hand a crawler an empty shell. Check what a plain request to your help center actually returns, confirm your robots rules allow the crawlers you want, and keep a real sitemap current.

Then there is llms.txt, a Markdown file at the root of your domain mapping your most important documentation for AI tools, and its companion llms-full.txt, which puts the documentation itself into one retrievable file. Jeremy Howard proposed the format in September 2024 and some IDE and agent tools look for it. Adoption is uneven and it does nothing for content that was weak to begin with, so generate both if your platform produces them automatically and treat them as an addition on top of clean content.

Writing for agents that take actions

The next reader does more than answer questions. Agentic systems change configurations, call APIs, and complete multi-step workflows on a customer's behalf, and your documentation is the instruction set they follow. Agents need the things a human would otherwise infer:

• Explicit prerequisites, stated inside the task

• Constraints and limits. Rate limits, plan restrictions, and expiry windows belong next to the step they govern, not in a reference table three pages away that retrieval will never pull alongside the instruction

• Exact error text with its fix, quoted verbatim

• Precise tool and API descriptions, because an agent will call something wrong if its parameters are described loosely

Protocols like Model Context Protocol let agents pull from several sources at once, which raises the cost of ambiguity. Each source has to stand on its own.

The problem nobody talks about: your documentation goes stale

Every fix above assumes your documentation reflects your actual product. When it does not, none of the structural improvements matter.

AI systems cannot tell when your product has changed. They will retrieve and cite an article about a feature redesigned three months ago, with no way to know the button has moved, the field has been renamed, or the workflow has changed entirely. What follows is predictable:

• Your chatbot gives specific, wrong answers with complete confidence

• Customers lose trust in self-service and stop trying it, which is the expensive part, because that habit does not come back when the article is eventually fixed

• Ticket volume rises for issues that should resolve themselves

Structural quality gets documentation ready for retrieval, and currency keeps it accurate. Both are required, and only one of them is a one-time project. This is documentation drift, and it takes three forms that structural advice never covers.

Conflicting articles are the version nobody checks for

Two articles that contradict each other are one of the most reliable ways to produce a wrong AI answer, and they are almost impossible to find by reading.

A human notices the contradiction because they remember reading something different last week. Retrieval does not. It pulls whichever passage scores highest, and if the older article is phrased closer to how the customer asked, that is what the answer gets built from. Neither article looks broken alone, which is why review processes that check one article at a time never catch this. Advice about duplicate titles does not help either, since two articles can carry completely different titles and still disagree about what a setting does.

Finding conflicts means comparing claims across articles rather than checking each in turn, which is what Pageloop's Help Center Audit does, alongside checking internal and external links and flagging the ones that come back broken, uncertain, or unreachable.

Screenshots go stale faster than the text around them

Alt text is the advice everyone gives, and it solves the wrong half of the problem.

A screenshot with perfect alt text is still wrong when the interface it shows no longer exists. The customer sees a toolbar that does not match theirs and assumes they are in the wrong place. The AI system, which cannot see the image at all, keeps answering from text describing the old layout, because the two drift together. Screenshots also decay faster than prose, since one UI refresh invalidates every image at once while leaving most sentences technically true.

Finding and fixing outdated screenshots is its own maintenance job. Pageloop handles the image side of Update directly: mark a change as a UI change and it suggests replacement screenshots, captured from the live product once you grant permission or drawn from uploaded media, a recorded flow, or an image already used elsewhere in your help center, with alt text generated for each. Every suggestion goes to a person before anything reaches a customer.

Doing this across a help center you did not just write

This guidance is easy to apply to an article you are writing today. Applying it to four hundred articles written by people who have since left is a different job, and the one most teams are actually facing.

Start where breakage is most visible, in this order:

• Your highest-traffic articles

• The ones behind the questions your chatbot currently answers worst, which you can pull straight from its logs rather than guessing at what customers are struggling with

• Anything covering a feature that shipped in the last quarter

Working through the list in slug order is how this stalls.

The ongoing half is knowing which articles a product change just invalidated. Pageloop's Find watches connected sources including Slack, Linear, Jira, and support conversations, and Update scans the categories you select against release notes or a recorded flow to work out which specific articles a change affects. You review each suggested change and accept or ignore it individually.

How to test whether your docs work for AI

You do not have to guess whether the changes worked:

1. Prompt your own content. Paste real support questions into your chatbot and compare each answer against the source article

2. Read one chunk in isolation. Copy a single section, strip everything around it, and see whether it still makes sense

3. Run a readability tool over the article to catch long, passive, multi-clause sentences

4. Mine your logs for the questions that return "I don't know" or a wrong answer, since those are your priority fixes and they arrive ranked by frequency for free

5. Fix, then retest and confirm the answer improved

Do the first two on a handful of your busiest articles before rolling anything out widely. Within an hour you will know whether you have a structure problem or a currency problem, and the fix differs for each.

Where to start

Getting the structure right is the foundation, and keeping it current is the work that never stops.

Pick your ten highest-traffic articles. Make each section self-contained, rewrite the headings as questions, add a short FAQ to each, then run the test loop and see what changed. That is roughly a week of work, and it tells you whether the rest of your help center has a structure problem, a staleness problem, or both.

If the second one is where your team is falling behind, that is exactly what Pageloop is built for.

FAQ

Does writing documentation for AI make it worse for humans? No. Descriptive headings, short sentences, consistent terminology, and self-contained sections all make an article easier for a person to skim, especially someone who arrived mid-page from a search result.

What is RAG, and why does it matter for my help center? RAG stands for Retrieval-Augmented Generation. It splits your knowledge base into chunks, retrieves the few most similar to a customer's question, and generates an answer from only those chunks. It matters because your chatbot never sees a full article, only fragments of one.

How long should an AI-friendly help article be? Long enough to answer the follow-up questions a customer will ask a chatbot. Covering edge cases matters more than word count, because a thin article gives the bot nothing to work with after the first question.

Do I need an llms.txt file? Only if your platform generates it for you, in which case turn it on and stop thinking about it. Hand-maintaining one is rarely a good use of an afternoon compared with fixing the articles it would point at.

Why does my AI chatbot hallucinate answers from my own documentation? Usually because it retrieved a chunk that was vague, ambiguous, or missing context, so the model filled the gap itself. That is a content problem rather than a model problem, and cleaner self-contained sections fix it more reliably than a better bot.

What should I do when two articles contradict each other? Decide which is correct, then fix or retire the other. Leaving both live means retrieval keeps picking between them, and you have no control over which one wins.

Does this apply to internal documentation as well as customer-facing docs? Yes, and usually more so. Internal wikis tend to be older and less consistently maintained, and they are increasingly connected to the same copilots your support team uses, so the same retrieval problems appear with less oversight.

Image Courtesy National Gallery of Art. Josephine and Mercie, Edmund Tarbell (American, 1862 - 1938)