Your Documentation’s New Reader Isn’t Always Human

AI is starting to blur a line that used to be fairly firm: product managers building things, and engineers writing product requirements. PMs are increasingly expected to spin up a simple working prototype with AI to show what they mean, rather than just describing it in a doc. The idea is still theirs. The engineering capability to build it usually isn’t. What’s actually happening is that an AI is doing the building on their behalf, which means the AI is the one reading the technical documentation, not the PM directly.

That shift has quietly exposed a problem with how most documentation is still written.

Docs built for humans, read by something else

A lot of technical documentation still lives as PDFs, slide decks, or web articles scattered across a developer center, sometimes behind a login wall. None of that is a problem for a person with a browser and some patience. It’s a real problem for an AI trying to parse it: logins can block access outright, and even when they don’t, formats built for human skimming (long PDFs, decks with information split across slides) burn through tokens (the units an AI model uses to measure and limit how much text it can take in at once) without giving back much useful structure in return.

I’ve seen this often in my experience, especially over the past couple of years. Product managers, data engineers and product owners trying to integrate with data delivery solutions lean heavily on AI to do it, but a surprising amount of their time still goes into manually pulling context together and attaching individual PDFs so their AI has something to work with.

MCPs (Model Context Protocol, a way for an AI model to pull data directly from a source) can fill part of that gap by giving an LLM direct access to data on demand. But that isn’t the same as a traditional server to server connection, and it isn’t the right layer for every case. A standard scheduled data pull or a routine report doesn’t need an LLM in the loop, and arguably shouldn’t have one: it’s one more thing that can go down, run out of tokens, or quietly shift its output when the underlying model gets updated. Traditional server to server delivery still has a place for exactly that reason. What’s changed is how fast people want to get the connection itself set up, and they’re increasingly using AI to do that part.

Writing for two readers at once

The practical answer, at least for now, is documentation written to work for both readers: clear enough for a person, structured enough for an AI to parse cleanly. Markdown is a natural fit. Anyone already using AI to help them build is generally comfortable with it already, so this isn’t asking PMs or engineers to learn something new.

I rebuilt a set of API documentation this way: pure Markdown, with linked JSON files giving a sample of each API call. Once that version started going out to customers, integration that used to take days or weeks started taking hours instead, because the AI on their end could immediately parse the request formats, the edge cases and the data quirks that normally take a human developer a while to absorb through trial and error. Fewer clarifying questions came back our way too, since most of what someone would have asked was already sitting in a format their AI could read directly.

What I take from this

I don’t think this stays a niche concern. As more of the people reading documentation are AI systems acting on a person’s behalf, documentation that only optimizes for human skimming is going to keep costing everyone time on both sides. I’d expect the format to keep evolving toward something that reads well for a person and parses efficiently for an AI at the same time, without bloating the token count needed to take it in. For now, the practical shift is a small one: write your docs assuming an AI reads them first.

All opinions and perspectives expressed here are solely my own and do not represent the views of my current or past employers.