How to Write Documentation for Humans and AI: A Practical Guide
Most documentation was written for one audience. It now has two.
Key takeaways
AI does not read your help center top to bottom. It splits articles into chunks and retrieves a few in isolation, so a section that leans 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.
Writing for AI and writing for humans is the same project. Descriptive headings, consistent terms and short sentences help both readers at once.
Delivery matters as much as wording. Serve clean Markdown or HTML, keep content out of JavaScript-only rendering, and treat llms.txt as a bonus.
To write documentation for both humans and AI, make every section self-contained and keep the structure strict. Give each section a descriptive heading, one topic and the context it needs. Serve the page as clean Markdown or HTML with a proper heading hierarchy. The changes that make a page retrievable for an AI system also make it faster for a person to skim.
Support chatbots, AI search tools and coding assistants now read the same knowledge base your customers use. A customer who hits a confusing article can search again or raise a ticket. A chatbot takes the article at face value and repeats it as a confident answer. A gap in the documentation becomes a wrong answer in front of a customer. To tell whether a wrong answer came from the model or from the article, see most wrong AI support answers are a stale doc in a confident voice.
This guide covers what to change, why each change helps, and how to check whether it worked.
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.
Human reader | AI system | |
|---|---|---|
How it reads | Skims and jumps between sections | Retrieves a few passages that resemble the question |
Missing context | Fills the gap from experience | Has nothing beyond the passage retrieved |
Ambiguity | Usually guesses right | Gives a vague answer, or a wrong one |
What it needs | Clarity and flow | Each passage carrying its own context |
Every fix on the AI side also helps a person who lands mid-article from a search result. That reader skipped the top of the page too.
How AI actually reads your knowledge base
Most documentation chatbots use retrieval-augmented generation, or RAG. The system splits your knowledge base into chunks of a few paragraphs and stores them in a searchable index. When a customer asks a question, it retrieves the chunks closest in meaning to the question. A large language model then writes an answer using only those chunks.
Chunking has four consequences for how you write:
Sections are read in isolation. A section that relies on an earlier paragraph loses that context entirely.
Anything the article leaves unsaid is unknown to the AI.
Chunk boundaries are unpredictable, so two related facts far apart on the page may never be retrieved together.
Retrieval runs on meaning. If your wording differs from how customers phrase their questions, the right section can stay buried even when it holds the answer.
kapa.ai's writing guide describes the same mechanics from the retrieval side. AWS's best practices for RAG applications reach the same conclusion: split large documents into smaller, self-contained ones with clear titles.
Structure: the foundation of AI-ready documentation
Use descriptive, question-style headings
Write headings the way customers type questions into a search bar. For humans, headings are navigation. For AI, headings signal what a section contains. A customer asking "How do I reset my password?" gets nothing from a heading called "Account Management". A heading called "How to reset your password" matches at once.
Three heading habits break retrieval. Vague headings such as "Overview" and "Additional information" describe nothing. Time-bound headings such as "What's new" go wrong the day the feature stops being new. Duplicate headings across articles give retrieval no way to choose. Two guides titled "How to set up the integration" should name Slack and Zapier instead.
Keep the heading hierarchy strict, too. Go from H1 to H2 to H3 without skipping a level, and never pick a heading tag for how it looks. A chunk carries its headings with it, so a clean hierarchy tells the AI where that chunk sits in the article.
Match each page to the question it answers
The Diátaxis framework sorts documentation into four types:
Tutorials teach by walking through an example.
How-to guides get one task done.
Reference pages list facts to look up, such as settings, limits and error codes.
Explanation covers the why.
Keep each page to one type. A how-to guide padded with background produces chunks that mix steps with theory, and the AI retrieves both when the customer wanted only the steps.
Keep one topic per section
A section covering several topics dilutes retrieval. A "Settings" section that covers password changes, billing, team permissions and two-factor authentication is four topics under one heading. Retrieve it to answer a two-factor question and the answer comes back noisy.
Split any section covering more than one distinct task. Splitting sections does not mean writing shorter articles. A long article with clearly separated sections retrieves better than a short one that mixes four tasks under vague headings.
Writing: how to make every section retrievable and accurate
Make every section self-contained
Self-contained sections are the first thing to fix for AI answer quality. Documentation usually assumes linear reading, with the introduction setting context for everything below it. A chunk pulled from the middle has no introduction.
Say an article opens with "This guide assumes you have created an account". Later it says "Go to the dashboard and click Configure". A chunk holding only the second line leaves the AI guessing which dashboard and which product.
The fix is to name everything inside the section:
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 survives as a standalone chunk. Apply the same rule to prerequisites and constraints. State a prerequisite inside the section that needs it. Keep a limit next to the step it governs: if an API token expires after 24 hours, say so beside the login steps. Phrases like "as mentioned above" are a quick way to find sections that are not self-contained.
Use consistent terminology throughout
Inconsistent naming is one of the least visible causes of poor AI retrieval. Say one feature is called "Workspaces" in the getting-started guide, "Projects" in the API reference and "Environments" in a troubleshooting article. Retrieval treats those as three different features. A customer asking how to create a Workspace gets the getting-started guide and nothing else.
Agree on one name per feature, concept and action, and keep the list somewhere writers can find it. A short reference page helps too. The page defines your core terms and states your product's rules and limits, so people and AI both have one place to check. Pageloop takes a product-specific term list and a style guide in its AI settings, so generated drafts use your names.
Replace vague pronouns with specific names
Pronouns cause trouble in retrieved chunks. "After configuring the integration, test it to make sure it is working correctly" leaves a chunk-bound AI unsure what "it" refers to. "Once the Slack integration is connected, send a test message from the Integrations panel" works anywhere it lands. Apply the same treatment to every "this", "that" and "the following" whose referent sits in another paragraph.
Long sentences fail the same way, and so does passive voice, which hides who does what. Take "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." Split it into two sentences: the requirement first, then the steps.
Formatting: what helps AI and what hurts it
Five formatting habits look fine to a person and trip up AI processing:
Symbols in tables. Checkmarks and crosses can get dropped when a table is flattened into text. Write "Yes" and "No", and fill every empty cell, since a blank could mean "not applicable" or "nobody filled it in".
Images carrying information no text repeats. A retrieval system reads text, not screenshots. Add alt text, and describe any process an image shows in the text as well.
Content in formats machines struggle with, such as PDFs, video walkthroughs and widgets rendered by JavaScript.
Unfenced code. Put examples in fenced code blocks with the language labelled.
"Click here" link text.
Content strategy: what to add to every article
Add a FAQ section to every article
Customers phrase their questions as questions, and retrieval compares the question against your content. A FAQ entry asking "Can I connect Slack to multiple workspaces?" matches that exact query. A paragraph that happens to contain the answer matches less closely.
Source the questions from your support inbox and your chatbot logs rather than from the article itself. The questions the article did not anticipate are exactly where your chatbot struggles. Keep three to eight per article, all on that article's topic, because one giant FAQ page chunks poorly.
Include exact error messages in troubleshooting articles
Customers who hit an error usually paste the exact message into search. A troubleshooting article that quotes the error text next to the fix matches directly. "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 helps AI find the right page
Metadata tells a retrieval system what a page is about. Docs-as-code platforms keep it in frontmatter at the top of each file, and help desks keep it in article fields. Either way, it is one of the cheapest parts of your documentation to fix.
Give each page a title that names the feature and the action, such as "Set up the Slack integration" rather than "Getting started". Write a one-to-two sentence description of exactly what the page covers. Tag articles by category, product area and plan, so the AI can return the right answer to the right customer. Use readable URLs too: /docs/setup-slack-integration describes the page before anything reads it, while /docs/page-1234 does not.
Delivery: making your docs easy for AI to fetch
Everything above assumes the AI can reach your content. Format decides most of that. Clean Markdown parses more reliably than a PDF. Markdown is also far lighter than a full HTML page, which carries navigation, styling and scripts alongside the text. Coding agents such as Cursor, GitHub Copilot and Claude fetch documentation during a session. A compact Markdown page fits in their context where a heavy HTML page may not. Some documentation platforms now serve Markdown to agents and HTML to browsers from the same source.
Rendering decides the rest. A page that assembles its content with JavaScript can hand a crawler an empty shell. Check what a plain request to your help center returns, confirm your robots rules allow the crawlers you want, and keep your sitemap current.
An llms.txt file is a Markdown file at the root of your domain that maps your most important documentation for AI tools. Jeremy Howard proposed the format in September 2024, and some platforms also generate an llms-full.txt file holding the full documentation text. Generate both if your platform does it for you. Neither file helps content that was weak to begin with.
Writing for AI agents that take actions
AI agents do more than answer questions. They change settings, call APIs and complete multi-step workflows for a customer, and your documentation is the instruction set they follow. Agents need everything a human would otherwise infer:
Prerequisites stated inside the task.
Constraints next to the step they govern. Put rate limits, plan restrictions and expiry windows beside the instruction they affect.
Exact error text with its fix, including the full error response for API calls.
Complete API descriptions, with every parameter, type and required field, because an agent calls an endpoint exactly as the documentation describes it.
The Model Context Protocol lets agents connect to outside tools and data, and some documentation platforms now expose docs through an MCP server. An agent pulling from several sources at once raises the cost of ambiguity, so each source has to stand on its own.
How to keep AI-ready documentation accurate
A well-structured article still gives a wrong answer if the product has changed since it was written. An AI system cannot tell that your product changed. It will retrieve an article about a feature redesigned three months ago and present it as current.
Two articles that contradict each other cause the same problem. Retrieval picks whichever passage scores higher, so the customer's phrasing decides which version they get. Decide which article is correct, then fix or retire the other. Update each article when its feature changes. Our documentation drift guide covers how to find outdated articles and how often to audit for them. Pageloop watches product changes and proposes the affected updates for your team to approve, so the articles your AI reads stay accurate.
How to test whether your docs work for AI
You can check the changes directly rather than guessing:
Paste real support questions into your chatbot and compare each answer against the source article.
Copy a single section, strip everything around it, and see whether it still makes sense.
Ask an AI agent to complete a common task using only your documentation, and note where it stalls or guesses.
Pull the questions from your chatbot logs that returned "I don't know" or a wrong answer. Those are your priority fixes, already ranked by frequency.
Fix the article, then rerun the same question to confirm the answer improved.
Run the first two on a handful of your busiest articles before rolling changes out widely. The results show whether you have a structure problem or an accuracy problem, and each needs a different fix.
Where to start
Applying this guide to an article you are writing today is easy. Applying it to hundreds of existing articles needs an order. Start with your highest-traffic articles, then the ones behind the questions your chatbot answers worst, then anything covering a feature that shipped last quarter.
For each of your ten busiest articles, make every section self-contained, rewrite the headings as questions, and add a short FAQ. Then run the test loop and compare the answers. For a way to find your worst articles first across a whole help center, see how to make your help center AI-readable.
Image Courtesy National Gallery of Art. Josephine and Mercie, Edmund Tarbell (American, 1862 - 1938)
Author
Fatema works across marketing and content at Pageloop. She has an academic background in Ecology, a side-life in fashion, and an irrational loyalty to milk coffee.
Other related content you might be interested in
