We can no longer write exclusively for a human audience, someone who reads carefully, asks follow-up questions, and fills in gaps with context and common sense.
I've bet you've seen it everywhere: "your docs need to be readable for agents." Agents, agents, agents, cue the Brady Bunch theme. Everyone is talking about agents taking technical writing jobs, AI this, AI that. But where are the actual solutions?
The technical writing industry has changed. We can no longer write exclusively for a human audience, someone who reads carefully, asks follow-up questions, and fills in gaps with context and common sense. Our docs now have a second audience. One that doesn't probe for answers, that doesn't ask for clarification, and fills gaps not with judgment but with hallucination.
The audience is agents. And we need to start writing for them.
Honestly, who actually wants to read pure reference documentation? If this → then that. Condition met → execute action. Technically precise and completely soulless.
The Diataxis framework has served us well, tutorials, how-to guides, reference, explanation. Clean separations, clear purposes. But it was built for human readers with patience and context. It wasn't built for agents. And it wasn't built for the developer at 11pm with a production issue who doesn't have time to wade through four pages of deployment documentation praying the answer is somewhere in there.
Most developers aren't reading docs on a Sunday morning for pleasure. They're reading because something is broken. So are we writing for the moment of curiosity or the moment of crisis? And now that agents are in the mix, consuming our docs to make decisions on behalf of that same frustrated developer, the question gets sharper.
What’s the bridge between barebones and overly informative?
What does great documentation actually do? To me, it answers the questions you hadn't thought to ask yet. The ones you didn't know you needed until you were already stuck.
An agent cannot ask follow up questions. It cannot pause mid-task and realize it needs more context. It cannot intuit that the edge case you didn't document is the one it's about to hit. It will simply proceed and fill the gap with its best guess, which is another word for hallucination.
Documentation that already anticipates the unasked question serves both readers. The human who didn't know what they didn't know. And the agent that cannot know what it wasn't told.
The goal has never been "write for humans" or "write for agents." The goal was always to write for the moment before the question forms.
We just didn't know we needed to say that out loud until now.
So what does this actually look like in practice?
Start here: before you write a single word, ask yourself two questions. What decisions are people reading this doc trying to make? And what will their likely next step be?
Not "what information do I need to convey?" That's the old question. That's how you end up with four pages of similarly named documentation that answers everything except the thing the reader actually needed.
The new question is about decisions and momentum. Where is this person trying to go? What do they need to know to get there? And what comes after that?
Something shifts when you write from that vantage. The document stops being a repository and starts being a guide. A guide with clear decision points, explicit next steps, and no assumed context is something both a human and an agent can actually use.
The decision your reader is trying to make isn't static. It changes depending on where they are in their journey.
Day 0 is testing. Day 1 is production. Day 2 is maintenance. Three stages, three completely different goals, three completely different things a developer, or an agent acting on their behalf, actually needs from your documentation.
A Day 0 developer needs to know if your product does what they think. A Day 1 developer needs to know exactly what to do and what happens if they get it wrong. And a Day 2 developer already knows your product but they're reading because something changed or something broke and they need the answer fast.
Trying to write the same doc for all three and you've literally wasted everyone’s time.
So where do you start?
Here’s three things you can do tomorrow:
- Audit your existing docs and ask one question for each one: Why would a reader click on this page? What decision does this doc help a reader make? If you can't answer that in one sentence, that’s a signal that you need to tighten the scope of the page.
- Identify which stage your reader is in. Are they Day 0, Day 1, or Day 2? Write to that stage's specific goal, not all three at once. A developer testing your product and a developer maintaining it in production are not the same reader. Stop writing like they are.
- If possible, end every section with an explicit next step. Not a "see also" or a list of related articles. If X → do Y. Give both your human reader and any agent acting on their behalf a clear path forward.
The conversation about agent-readable documentation isn't going away. But talking about it without changing how we actually write is just noise.
We now have somewhere to start.
Top comments (0)