Writing for People Is Persuasion Now. Writing for Agents Is Instruction.

Poor core documentation was one of the top reasons people uninstalled the flagship product at a software company I worked for. Not a support ticket. An uninstall – somebody opened the docs, failed to find what they needed, and removed the product. Fixing that was my job: take a scattered pile of documentation websites and consolidate them onto one platform.

So I spent months on it. Researching platforms, prototyping, testing, building the services around them, rejecting the ones that demoed beautifully and buckled the moment real content went in. I lost sleep over it and I worked weekends on it, at the kitchen table, with the particular low-grade dread of knowing the recommendation was mine and the blast radius wasn't. By the time I presented to several dozen people across engineering and marketing – multiple countries, a handful of us in one small office – I was about as certain as I get.

Then a friend spoke up. An engineer I'd known and worked alongside for years. What he said was close to this: "You're making this recommendation, but I don't think you understand how important this is. I don't think you put much thought or effort into this or care about it as much as we do. You should have had us make the decision."

It flattened me. From a stranger I'd have shrugged it off in the parking lot, but this was someone who knew my identity, my values, how hard I work, and he was telling a room full of colleagues that I'd phoned in the thing I'd been bleeding over for months. I got defensive and kept it professional, which is the most anyone manages in the moment.

He was literally in the next room. I went and asked him what the hell that was, how could he say that when he knows me. We talked it through and he apologized, and then the real thing came out: those docs were his baby, close to his whole job, and he was terrified that changing the platform would make them worse and eventually cost him his job. He had a conversation running in his head. I had mine. They collided in front of an audience.

I've cared about docs for a long time, back when every reader of it was a person.

Who reads the docs now

GitBook, from its own traffic data, reports that "the majority of readers of your documentation are now AI agents." Their framing: "That's not a prediction – it's in our own traffic data, and likely yours too." Take the first half seriously and the second half as what it is. GitBook sells documentation tooling, they measured their own traffic, and "likely yours too" is a suggestion rather than a finding. Nobody has handed you your numbers. You'd have to go look at them.

The part of that post I keep coming back to isn't the majority claim anyway. It's what comes after: "the agent isn't the end of the line. It reads your docs, paraphrases them, and then hands an answer to a person who may never see your page. So every doc now has two audiences with different needs. Humans want narrative and context. Agents need structure and unambiguous facts."

The human reader didn't disappear, then. The human reader moved a step downstream and now receives a paraphrase written by something with no stake in whether they succeed. Mintlify's 2026 State of AI report, quoted by Tom Johnson, lands in the same place: documentation is becoming "infrastructure that serves two audiences at once," where humans still need docs that are "clear, navigable, and well-organized" while agents need them structured and easy to parse programmatically.

I want to be careful about scope. All of that evidence is about documentation specifically. The bigger claim I'm going to make, that writing has split into two crafts, is mine and not theirs.

Humans and retrieval systems fail differently

The mechanical difference between the two readers is not taste, it's what happens when context is missing. Pageloop's breakdown of how retrieval reads a page states it plainly: "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." 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."

That asymmetry is the whole practical problem, and it's the same one underneath how retrieval actually reads. A person who lands on your rate-limit section without ever seeing the auth section usually senses that something upstream is missing and goes looking for it. A retrieval system answers confidently with the half it got, which is a Cheap Yes with a citation attached.

Two crafts or one standard: GitBook argues both

The most useful thing in my research this week was a company publishing both sides of the argument within days of itself. GitBook's companion argument starts from a real observation: "When a person reads docs and follows them, there's a layer of human judgment between what you wrote and the outcome… Agents don't do this – they literally can't! When an agent reads your docs, it executes them literally and moves on – with no pause, and no built-in, human moment of doubt." Their conclusion is docs as infrastructure, and that "the forgiveness margin collapsed entirely."

Then comes the objection: "These aren't competing priorities. A doc that's structured well enough for an AI to retrieve and summarize accurately is usually also a doc that's well-written enough for a human to follow." Good writing and machine readability, they argue, "tend to agree on the same virtues – plain language, complete sentences, explicit statements, concrete examples."

They're right about the virtues, and I'm not going to pretend otherwise to make my headline cleaner. Plain language serves both readers. Explicit statements serve both readers. A concrete example is the single best thing you can put in front of either one. If you were hoping the agent era gives you permission to write worse prose for humans in exchange for cleaner structure for machines, it doesn't, and the trade you're imagining isn't on the table.

The split is somewhere else. It isn't in the prose, it's in the job. Writing for a person is persuasion, in the plain sense: you are trying to get another human being to hold a belief that you hold, and everything about narrative, order, example, and emphasis exists to move them from where they are to where you are. Writing for an agent is instruction. There's nobody to convince. Precision all the way down, phrased in natural language but shaped more like pseudocode, where an ambiguous sentence isn't a stylistic weakness but a branch you failed to specify.

So the virtues converge and the jobs diverge, which means the decision in front of you isn't how to write the sentence. It's which of those two things the sentence is for, and that decision happens before any of the formatting advice becomes useful.

What actually changes on the page

Most of the concrete craft advice in this territory is genuinely good, and you've probably already seen it: self-contained sections, descriptive headings, clean Markdown, stated prerequisites. GitBook's practical guidance is my favorite version because it's specific about headings. Make them carry information. "'Token lifecycle' beats 'Overview'", and "'Rate limits' becomes 'Rate limits: 100 requests per minute'". Their line about consequences is the one I'd tape to a wall: "A renamed heading is a broken API."

Their self-test is better than any checklist: "Read your page the way an agent does: strip the layout, the screenshots, the visual hierarchy. Does the raw text still answer the question?" Run that on your onboarding guide sometime. The good news is that a page which survives it is also a page a tired person can use on a phone at 11pm.

Here's my one complaint about the whole conversation. Nearly everyone writing about this treats it as a formatting problem. Chunk your sections, fix your headings, ship an llms.txt, done. Formatting is the cheap part. The expensive part is that you now have to know, sentence by sentence, whether you're trying to convince someone or trying to specify something, because those two goals want different drafts and most documents I read are quietly attempting both and landing neither.

Where the reframe fails

The advice to write mental models instead of exhaustive reference is conditional, and the conditions matter. Breunig's five rules, as set out by AgentPatterns, put it well: "Agents enumerate; humans orient." What's left for the human-facing document is mental models, design intent, design exclusions, and trust calibration, with the stated goal being "to prepare your audience to prompt an agent effectively."

That same source is careful enough to name when it breaks, which is why I trust it more than the checklist posts. AgentPatterns' stated conditions are that your reader has to actually be paired with an agent at read time, that the surface must not itself be a contract, and that the risk of stale training data has to be bounded. Regulated SDKs and audited public specs fail the second condition outright. For those, the parameter table isn't a convenience wrapped around the real content, it is the artifact, and swapping it for a well-told mental model is a downgrade dressed as modernization.

Knowing which kind of document you're holding is most of the skill. It's the same question as who the PRD is for now, and the same one behind who still reads.

The one skill underneath both

Persuasion and instruction pull apart at the surface and share a single prerequisite, which is knowing what you actually think. You can't move a person toward a belief you haven't got, and you can't specify behavior you haven't decided on. Agents will happily generate the prose in either register, which means the writing is no longer where the difficulty lives. The difficulty is the opinion, which is the judgment layer stated in one sentence, and also what replaced knowledge as the moat.

I have a degree in Religious Studies and Poetry. Nobody hires a poet to consolidate documentation platforms, and yet the most useful thing I brought to that project was a degree's worth of being made to ask what a text was for and who it was addressed to, over and over, until the question became reflex. That question is now load-bearing infrastructure. It used to be an English seminar.

Ten years ago a friend told a room of colleagues that I hadn't thought hard enough about the documentation. He was wrong about me that day, but the standard he was holding me to was the right one, and it has gotten harder to meet that standard in the years since the readers stopped all being people.

If your team is staring at an artifact that's trying to persuade and specify at the same time and failing at both, that's a question worth answering once, properly. Email matthew@fieldway.org to discuss.

Sources

• GitBook, 5 ways to improve your technical writer skills for 2026
• GitBook, Humans are still the real readers of your documentation
• AgentPatterns.ai, Human-Facing Docs in the Agent Era: Mental Models Over Reference
• I'd Rather Be Writing, From developer experience to agent experience (quoting Mintlify's 2026 State of AI)
• Pageloop, How to Write Documentation for Humans and AI
• The Skip, Inside PM at Stripe