Course
6 Steps to Documentation You Don't Write
Lesson 5 of 6
A customer wants to know whether your product can restrict exports by role. They don’t open your documentation. They ask the AI assistant already open on their second monitor — Claude, ChatGPT, whatever their company standardized on — get a clear answer in four seconds, and act on it.
The answer was confident, specific, and eight months out of date. Nobody told you it happened.
60+ product and documentation teams at B2B SaaS companies, interviewed through 2025 and 2026: teams that lost their writers, teams that never had one, and teams where the writers never left.
Every lesson so far has assumed your reader eventually lands on your documentation. That assumption is the one that broke first.
The reader who never visits
Publishing used to be the finish line because the reader came to you. They searched, they landed, they read, and the only question worth asking was whether the page was any good.
Three things now happen instead, and two of them never touch your site.
Someone asks the AI assistant inside your product, if you have one. Someone asks the AI assistant on your documentation portal, if you have that. And increasingly, someone asks their own general-purpose AI assistant, which knows nothing about your portal in particular and answers from whatever it absorbed during training or can fetch on request.
That last one is the awkward case, because you have no analytics on it, no log of it, and no way to know it went badly. The customer walks away feeling informed. They just happen to be wrong.
Your documentation now has two audiences, and only one of them ever visits your site.
Where the answer comes from
When an AI assistant answers a question about your product, the content comes from one of three places, and the difference decides whether you’re happy about it.
A snapshot from training. Your docs as they existed at some point in the past, blended with forum threads, old blog posts, and a competitor’s comparison page. This is the default, and it’s the source you have the least control over.
A live fetch. The AI assistant retrieves your current pages during the conversation, if it can reach them and parse them. This is the good case, and it depends entirely on properties of your published content that nobody on your team is currently responsible for.
Your own AI assistant, on your portal or inside your product, answering from your content. This is the case you control completely, and it’s the only one where you can see what was asked.
An AI assistant’s answer is exactly as current as the copy it can reach. If it can’t reach yours, it answers from a stale summary, and nobody tells you.
Here’s what that means on a normal Tuesday. You correct a page at 10am. Your portal serves the new version immediately, and an AI assistant that fetches live will quote it the same day. An assistant answering from a training snapshot will keep repeating the old version for months, and it has no way to know it’s doing that.
So publishing a correction fixes the copy. Whether the correction reaches the person asking depends on which of the three sources answers them.
Real story: teaching the AI assistant your house style
A product manager at a European CRM vendor (B2B SaaS, 500+ employees) described the setup his team landed on: “We have an MCP with our PDF documentation updated on it. So Claude knows the style of our documentation.”
The payoff went beyond accuracy. The assistant started producing drafts and answers that matched their conventions, their terminology and their way of explaining things, because it was reading their material rather than the internet’s average opinion about their category.
Now look at the word “updated” in that quote, because it’s carrying the whole arrangement. Their source is a PDF, which means it’s a copy, which means someone has to remember to refresh it. On the day nobody remembers, the assistant keeps answering confidently from a version of the product that no longer exists. It works, and it works because a person maintains it.
That’s the general shape of this. Whether an assistant is useful or quietly harmful comes down to how your documentation is published and how directly it can be reached, which has nothing to do with how well it’s written.
What makes content readable by a machine
None of this requires a strategy. It requires five properties, and portals routinely fail two or three of them.
One canonical copy. If the current truth lives in a PDF someone exports monthly, an internal wiki, and a published portal, an AI assistant will find whichever it finds and treat it as authoritative. Exports are snapshots, and snapshots go stale silently.
Reachable without a login, and without running your JavaScript. Some crawlers render pages; plenty don’t. A page that assembles itself in the browser can arrive as an empty shell, and this one catches teams out, because the page looks perfect to a human and returns nothing to anything else.
Structure that survives stripping. Headings that describe content, one topic per page, stable URLs, and terminology that doesn’t drift between pages. When formatting is removed, what’s left should still make sense in order.
Explicit versions and dates. A model has no way to know that a 2024 page describes a screen that no longer exists unless the page says so. Version labels and last-updated dates are for machines now as much as for people.
Consistent naming. This one isn’t about markup at all. If your product calls the same thing three different names across three pages, a model asked about the third name will answer from the weakest page.
The failure that costs the most time
Ask a model about anything with your own syntax — a config schema, a webhook payload, a proprietary query format — and it will produce something that looks exactly right and doesn’t run.
The head of product at a data platform vendor (1000+ employees, APAC) named this as a specific reason his team preferred plain Markdown docs in a public repository over anything more elaborate: models frequently generate the wrong JSON structure for a specific platform, and his team had no appetite for spending time fixing it.
The pattern is consistent. General concepts, models handle well. Your specific format, they invent with total confidence.
The more particular your product’s syntax, the more fluently a model will make it up. Fluency is not accuracy, and your customer can’t tell the difference.
Which points at where your effort goes: exact structures — schemas, payloads, parameters, error codes — need to be available in a form a machine can copy rather than reconstruct. That’s less about writing and more about publishing them where they can be read.
Where this is easier, and where it’s manual
Any published documentation can be made machine-readable. Static site generators produce clean HTML, you can serve a plain-text or Markdown version of each page, you can maintain a file listing your key URLs for crawlers, and you can decide as a team that the portal is the single source of truth. It’s all configuration and discipline.
Documentation platforms have started doing this by default, since it’s the same problem for all their customers. In ClickHelp, for example, published content is served in machine-readable form alongside the human-facing pages, and the AI answer sits inside portal search and in a widget you can put in your product or on your site.
The reader side is the newer part. Your customers can connect their own agent (Claude, Cursor, ChatGPT) directly to your published documentation, so it reads your current content instead of guessing from a training snapshot. The agent sees exactly what that reader is entitled to see: public publications for anyone, and for a reader with an account, the restricted publications they already have access to. Read-only, and you decide whether readers can connect at all.
That turns the last row of the checklist below from “a training snapshot, and we don’t know from when” into the live-fetch case, which is otherwise the one row you have no way to influence.
Your artifact: the answer availability checklist
Stop asking whether your documentation is published. Start asking where the question gets answered, and whether that answer is yours.
For each place a customer might ask, decide whether they get a current answer, and where that answer comes from.
| Where the question is asked | Current answer? | Where it comes from |
| Your documentation site | Your published pages | |
| Search inside your portal | Your published pages | |
| Inside your product | Assistant, help panel, or nothing | |
| Support | A person reading your docs | |
| Google or another search engine | Your pages, or somebody else’s | |
| The customer’s own AI agent | Live fetch under their account, or a training snapshot |
The last row is the one to sit with. Until you do something specific about it, the entry there reads “a training snapshot, and we don’t know from when.”
The number that matters is the count of rows where the answer is both current and yours. Most teams have never counted it.
The other consumer: your own colleagues’ tooling
Your documentation is starting to be consumed by systems rather than people. QA teams generating test cases with a model get materially better results when the model is grounded in current documentation instead of inferring behavior from ticket titles and code. Connecting an agent to your published docs is the same mechanism your customers use, pointed inward. Support teams draft replies against it. Sales assistants answer security questionnaires from it.
Each of those is a team that now has a direct interest in your documentation being accurate and reachable, which is a different conversation than asking them for a favor.
One caution, since it cuts both ways. If test cases are generated from documentation and the documentation is wrong, the tests encode the error and both sides agree with each other permanently. Something has to stay anchored to the product itself.
Documentation is becoming something systems consume as much as something people read, and systems never complain that it’s out of date.
When your docs are behind a login
If your documentation requires authentication, one row of the checklist closes for good and one behaves differently than you’d expect.
External search engines are the closed one. Protected content is invisible to them, permanently, and no amount of structure will change it. That’s the price of restriction and you already accepted it.
The customer’s own agent is the interesting case. Today the workaround most teams use is to export the docs and hand the file to a model, which manufactures exactly the stale disconnected copy this lesson has been warning about, and sends your restricted content somewhere you no longer control it.
Reader authentication removes the need for that. The customer connects the agent under their own account, and it reads the publications that account is entitled to, current at the moment of asking. No export, no separate copy to keep current, and access follows the same permissions you already granted that reader.
Everything else works as it does for public docs: search inside your portal, an AI assistant inside your product, support answering from current pages, internal tooling. Fill the checklist in anyway. Restriction costs you one route to an answer, not the exercise.
What to do this week
- Ask a model about your product the way a prospect would, three questions, no context given. Note what’s wrong. Then check whether the correct answer exists on a public page at all — if it doesn’t, that’s a content gap, not a distribution problem.
- Check one published page the way a machine sees it: fetch it without a browser, or just disable JavaScript and reload. If the content disappears, that’s your first finding.
- Find your exports. Any PDF or copy of the docs living outside the portal is a competing source of truth. Decide which one is canonical and say so.
- Fill in the checklist for one product area. Six rows, ten minutes.
- Ask QA and support whether they’re feeding your documentation into any of their tooling. The answer is often yes, and nobody mentioned it.
Which leaves one question. Everything in this course so far runs on you paying attention to it, and nobody pays attention to the same thing forever. There’s no arrangement that fixes that. But there is a difference between a process only you would miss and one that several teams would notice stopping, and the last lesson is about moving from the first to the second.
FAQ
Should we block AI crawlers from our documentation instead?
Decide it separately for training and for search, because they aren’t the same crawler. OpenAI, for one, splits GPTBot from OAI-SearchBot, so you can stay out of training and still be discoverable. Blocking both is a real choice some companies make for competitive reasons, and the trade is that your product gets described by whatever else the model absorbed rather than by you.
How do I know what a model currently says about us?
Ask it. Three questions a quarter, written down, compared to last quarter. It’s a crude instrument, and it beats the alternative of never checking.
Is this only relevant for developer-facing products?
It’s most acute there, because code and configuration invite invention. But a prospect asking whether your product supports SSO is the same mechanism with less obvious symptoms.
We just rewrote our docs. Will the model see the new version?
The one that fetches live, yes, immediately. The one answering from training will keep repeating the old version for as long as its snapshot lasts. That gap is the thing to plan for, not to be surprised by.
Our documentation is small. Does this scale down?
It scales down better than most things in this course. Five properties, one canonical source, six checklist rows. A twelve-page portal can be made machine-readable in an afternoon.
