We Wrote the Documentation for Your AI, Not for You
Documentation was always the worst part of the job. Boring, yes. But that was never the real problem. The real problem was who you were writing for.
It was never one person. On every project it was a stack of people with different needs and different expectations. One of them needs to change the booking confirmation email. Another needs an extra schedule for the game. Neither of them needs the other forty pages. So you write for everyone, and it fits nobody. Then somebody writes a second document explaining the first. In most FAQs and guides the devil himself would break his leg, and Google’s documentation, in general, made me nauseous.
I have shipped a lot of projects in ten years. Most of the documentation we wrote was abandoned. Some of it immediately, some a few months or a few years later. Not because anyone was careless. While the team is still there, nobody needs it, because everyone already knows how the thing works. By the time somebody does need it, the people who knew have gone, and the document describes a project that no longer exists.
The audience problem
Call it what it is. Documentation has an audience problem, and no amount of writing effort solves it. The developer, the marketer and the owner need three different documents from the same facts. Write one and it serves nobody. Write three and you now maintain three things that drift apart.
For thirty years this was simply the condition of the work. The reader was a person, one person at a time, and you had to guess which one.
The reader changed
That is no longer true. The reader can be a model.
Think about who your assistant is by now. You have spent more working hours with it this year than with most of your colleagues. It has seen your projects, your style, how you take in information, what you skip. It knows whether you want the command or the explanation.
So the documentation does not need to fit you. It needs to fit the model, and the model fits you.
Write one source. Dense, technical, complete. Not friendly, not for beginners, not for experts, just accurate. The model reads it once and gives each person the version they actually asked for, in the words they use. The developer gets operation names and limits. The marketer gets “yes, you can change that yourself, here is where”. The owner gets one sentence and a cost.
The audience problem is not solved by writing better. It is solved at the point of reading.
This already exists, partly
I am not the first person here, and it is worth saying who was.
In 2024 Jeremy Howard proposed llms.txt, a plain file at the root of a website that gives AI systems a clean view of what matters. Anthropic, Stripe, Vercel and Cloudflare publish one now. Around one site in ten does.
Update, 21 September 2026: Claude Code now reads it too. Version 2.1.277, released on 18 September, checks for AGENTS.md in any project that has no CLAUDE.md of its own. It is a fallback rather than a merge, so a file written for one agent is never silently mixed with one written for all of them, and the behaviour can be turned off in the settings. A convention that was a proposal when this article was written is now the default in the tool that started the vendor-specific version of it.
Coding agents have AGENTS.md, a file at the root of a repository that tells the agent how to build, test and change the project. More than thirty tools read it, and since March it has been stewarded by the Agentic AI Foundation at the Linux Foundation, alongside MCP.
WordPress itself is trying the same idea inside the site: Guidelines, a Gutenberg experiment where owners write their content standards for editors and AI tools to read, was proposed for core this summer and held back until it shows real adoption.
And last week, on 8 and 9 September, W3C and GS1 held a workshop in Zurich called “E-Commerce for humans and AI agents”. GS1 Digital Link can put a brand-controlled URL inside the barcode on a physical product, so an agent can resolve the thing in your hand to authoritative data.
So machine-readable documentation is a real category with real backers. Good. But look at where all of it points.
It points at the sale, not at the years after
llms.txt is described as a way to become “a brand agents can transact with”. The GS1 workshop is about agents buying things. AGENTS.md exists so an agent can act on a repository.
In every one of these the agent is the consumer of the documentation. It reads so it can do something: buy, build, deploy.
Nobody is pointing this at the ten years after the purchase. Why is the dishwasher beeping. What does error E24 mean. How do I descale this. Is that part still made. Which setting on this router actually matters. The manual for those questions is a PDF written once for nobody in particular, and the owner has already stopped reading it and asked a model instead, which answers from whatever it absorbed from forums.
This is the same mistake I wrote about with content management systems. Everyone optimises the moment of launch. The cost lives in everything that comes after.
The manual should be written for the owner’s agent
Here is the idea, then. Every product that a person has to operate, digital or physical, should ship a document written for the owner’s AI. Not a chatbot on the vendor’s website. A document. Dense, exact, complete, in a form any agent can read. Your washing machine, your car, your accounting software, your website.
The agent is not the consumer of that document. It is the teacher. It reads the whole thing once and explains the part you need, when you need it, in your words.
This costs a vendor nothing and saves them plenty. Every question the owner’s own assistant answers is a support ticket that never arrives, and nobody had to build an app or a chatbot to get it. The first companies to publish machine-readable documentation were the ones who saw that early: their support desk is an expense, and a document is cheaper than a call centre.
A customer who gets a straight answer at nine in the evening does not open a ticket, does not return the product and does not write the bad review. Happy customer, happy owner.
One caveat, and it is not about money. If a model paraphrases a manual badly, the mistake looks like the vendor’s fault. That is why the refusal rule matters more than the writing does.
Where it stops
Two limits, and the piece is not honest without them.
A model paraphrasing a gas appliance manual is a different risk from a model paraphrasing a web tool. Safety-critical instructions need exact text and a rule to refuse, not a friendly summary. The document has to say “quote this, do not explain it”, and the agent has to obey.
And a document cannot make a model honest. It can only make the truth available and make refusal easy. The most important line in any documentation written for an agent is the one that says: if it is not written here, say “not documented” and check. Without that line you have built a confident liar with better sources.
What we did
We build a WordPress plugin, Fabrement, that lets an AI agent write real blocks, templates and pages for a site. Our documentation had the same problem as everyone’s. Two ways to use the product, more than seventy operations, a code policy, a design system, and three kinds of reader.
So we stopped writing it for people. There is now one document written for the model: what the plugin can build, what it cannot, how to connect an agent to a site, and what it means when something does not work. It does not try to sell anything, and it states the limits plainly, including the ones we would rather not advertise. Anything deeper than that, the rules governing each individual operation, the agent fetches for itself once it is connected, which is the part no document should try to freeze.
You can test the idea in thirty seconds, without installing anything. Paste https://fabrement.com/AGENTS.md into your AI and ask what Fabrement can and cannot do. Then ask it something we do not support. A good answer is “not documented”.
The part I find more interesting is not built yet. The next step is a guide for each site, generated from the site itself: which blocks exist and what they are for, the design tokens, the templates, the content types. Documentation nobody writes and that cannot go stale, because it is produced from what is actually there. The only part a person would write is intent: why the buttons are global, what marketing may change, what must never be touched. Today that still lives in somebody’s head, and that is the piece we are building next.
That is the whole idea. Not that the agent remembers how your project works. That it is written down.
Related articles
Why Some Standards Survive and Others Don’t
I lost most of the team standards I tried to keep across three teams. Two held for eight years. What saved them…
Website Builders Were Made for People. What Happens When AI Is the User?
Builders hide code behind buttons so people don't have to write it. AI can write the code, but not the judgment. Why…
WordPress MCP Adapter vs Fabrement
The official MCP Adapter is the bridge that lets an AI agent call what WordPress plugins register. Fabrement is a plugin with…