Writing

Your Docs Have a Second Reader Now

Something reads your API docs that has no eyes, and it reads the page, not a special file. Clean, structured output is a structural advantage the subscription model is built to ignore.

Something started reading your documentation that does not care how it looks.

It does not see your theme or scroll your sidebar, and it never noticed that you finally fixed the dark-mode contrast. It fetches a page, strips it to text, and tries to answer a question or make a call. By Cloudflare’s count, automated traffic passed human traffic for the first time in mid-2026. A meaningful slice of the reading done against API documentation now happens with no eyes at all, and most docs are still written as if every reader has them.

Two readers, one source

Documentation Is the Contract Surface makes the case that documentation became the surface humans and agents both ground on. That is two audiences with opposite needs reading the same pages. The human wants layout, navigation, and a sense of place. The agent wants the reverse: the page’s text and structure, pulled into a context window without chrome to skip, JavaScript to execute, or a headless browser to drive.

You cannot serve both by picking one. You serve both from the same source. The page the human reads and the text the machine pulls off it come out of one render pass, so what the agent parses is the structure you shipped, not a hand-kept mirror that drifts. A clean static page strips to text predictably; a JavaScript app that assembles itself in the browser does not. The same build also drops a flat llms.txt and llms-full.txt beside the HTML for tools that want a single plain-text index, but that is a convenience, not the main channel. The main channel is the page.

# Cheese Store API

> A sample REST API, documented with Sourcey.

## Endpoints
- [List cheeses](/api/list-cheeses): GET /cheeses
- [Add a cheese](/api/add-cheese): POST /cheeses
- [Authentication](/guides/auth): API keys in the Authorization header

That plain-text view is boring on purpose, and so is the HTML underneath it once you strip the theme: the docs with the cinema removed, which is exactly what the machine reader wanted all along.

What the incumbents shipped

A hosted docs platform optimizes the surface that closes the deal, and the surface that closes the deal is the polished human one in the demo. The agent does not attend the demo. It has no seat in your plan and no line in the contract. To a subscription business, a first-class machine surface is a cost with no buyer attached.

So when the machine surface became table stakes, the incumbents shipped it the way you ship a cost: as a checkbox. By 2026 the hosted platforms generate llms.txt and even MCP endpoints from your docs, on their domain, under their plan. Generated is the operative word. It demos well to the human buyer, and almost nobody audits what is in it, because the reader it serves cannot complain and does not pay. The reader growing fastest gets the surface examined least.

The byproduct that becomes the moat

Sourcey emits the machine-readable surface because it is a renderer sitting on top of source you own, not a platform selling a hosted experience. Once the source graph is in hand, the clean pages, the search index, and the plain-text views are nearly free to produce; they fall out of the same build that makes the HTML. There is no tier to unlock them, because there is no platform underneath to meter them.

That inverts the usual order. For a hosted docs product, machine-readability is a feature it has to be talked into shipping. For a tool that already owns the source and outputs static files, it is a default it would have to go out of its way to remove. The advantage is not cleverness; it is that the machine reader and the file owner want the same thing, and the subscription model wants something else.

Write for the reader that cannot complain

The human reader tells you when your docs are bad. They file issues, they post on Hacker News, they email. The agent will not. It will quietly ground on a stale endpoint, invent a parameter you renamed, and hand your user a call that 400s, and you will never see the bug report. The second reader is silent, which makes the quality of what you feed it your problem, not its.

Owning your output and emitting a machine view from it is how you stop guessing which reader you built for. You built for both, from one source, and you can prove it by reading what the agent reads: the same pages, stripped to text.