There’s a specific kind of dread that sets in when you open a documentation folder and realize the AI didn’t write to your users. It wrote at them. Nobody reads it.
I’ve spent more time than I’d like to admit inside other people’s documentation. Old Google Docs written by engineers who left years ago. READMEs that contradict each other across directories. Onboarding guides that explain what a for loop is to someone who just submitted a pull request. When I took on a documentation overhaul for a large technical tutorial repository, I had a clear picture in my head of what bad docs looked like. Then I started working with an internal IDE coding assistant to help generate them, and I discovered a new category of bad entirely – docs that look thorough, move fast, and quietly fail the people they’re supposed to serve.
While sifting through the plethora of emoji-filled markdown files, I realized the problem isn’t really that AI writes poorly. The problem is that AI writes a lot, and volume has a way of masquerading as quality. There’s a more fundamental issue underneath the volume problem: technical writing is a craft, and generating text is not the same thing as practicing it. Good documentation is an act of translation. You’re taking what lives in a codebase and in the heads of the people who built it, and making it legible to someone who has neither. That requires knowing who that person is. AI, by default, doesn’t know and most of the time nobody tells it.
The pitch is obvious. You have a codebase, a deadline, and no technical writer. You point an AI assistant at your repo and ask it to generate documentation. Minutes later, you have pages of organized, structured, grammatically correct output. It covers every function, explains every parameter, it even includes examples.
What you often end up with is twelve files and no front door.
A study on AI-generated regulatory documents found that AI output ran 3-5x longer than human written equivalents, with systematic repetition patterns throughout – and yet 35% of summaries were still missing essential study design elements, with complete omission of certain required components. The length wasn’t a sign of care, it was a structural artifact of how the model was optimizing. More coverage felt like more value, so it produced more coverage.
The same pattern plays out in technical docs. An AI assistant asked to “document this codebase” will document the codebase. It might also explain what a REST API is, describe what authentication means, or note, several times, in slightly different words, that you should replace placeholder values with your actual credentials. It fills space because it has no way of knowing what your reader already knows – unless you tell it.
The AI didn’t make a judgment call about your reader. It couldn’t. Nobody gave it the information it needed to make one. That’s not model failure, that’s a writing failure that belongs to whoever hit generate and walked away.
Working through the documentation overhaul of that tutorial repository, I ran into the same problems on repeat. They cluster into three patterns worth naming,
The Over-Explainer. The AI assumes a reader who knows nothing. It defines terms that any competent practitioner has internalized. It contextualizes concepts that don’t need context. The result is documentation that feels condescending to the audience it’s meant to serve and actively obscures the information they came for by burying it in setup. A developer who wants to know how to authenticate to an API endpoint doesn’t want a paragraph explaining what APIs are. That paragraph isn’t neutral, it’s friction, and friction at the wrong moment is the reason people close a tab and go to Stack Overflow instead.
The Repeater. Since AI models generate text without holding a structural view of the whole document, they restate the same information across sections without realizing it. Installation prerequisites appear in the introduction, then again in the getting started guide, then again in the troubleshooting section – sometimes phrased differently enough that a reader isn’t sure they’re looking at the same requirement. This creates a trust problem. When documentation contradicts itself, even slightly, users lose confidence in its accuracy and start second-guessing everything. A technical writer knows the whole document. An undirected AI knows only the section it’s currently producing.
The False Completeness Trap. This one is the most insidious. Autogenerated docs tend to be thorough about the obvious and thin on the hard parts. They’ll document every parameter of a straightforward method and say almost nothing about the edge case that trips up every new user. They generate the shape of complete documentation without the judgment to know where depth is actually needed. You end up with a document that looks finished, (that would pass a quick skim), but fails the user at the exact moment they need help the most. Coverage without prioritization isn’t technical writing, it’s an index.
None of this is a flaw in the model. It’s a flaw in the assignment.
When you ask an AI to “generate documentation for this repo,” you’ve given it a task with no constraints on audience, no indication of assumed knowledge, no scope, and no definition of what “good” looks like in this context. The model does what any generative system does with an underspecified prompt: it maximizes coverage and minimizes obvious gaps. It produces something that’s hard to fault on a quick read and fails on a careful one.
Missing context is the top barrier developers cite when working with AI-generated output – reported more often than hallucinations as the cause of problems. That finding holds for documentation just as much as it does for code. The model isn’t wrong, it’s working with incomplete information about the human on the other end, because that information was never supplied.
This is exactly what technical writers carry that AI doesn’t: accumulated knowledge of how real people fail with a product. The places where everyone gets stuck. The assumption buried in step three that nobody says out loud because the team has internalized it. The difference between how the API behaves in development versus production is clear if you built it and invisible if you didn’t. None of that is in the codebase. It lives in the people who watched others struggle with it, and it enters documentation through the judgement of someone who writes with that knowledge in hand.
The solution isn’t to stop using AI for documentation. It’s to stop asking AI to write documentation and start asking it to write documentation for a specific person who knows specific things and needs to accomplish a specific task. That’s a different prompt and it produces a different output.
The most effective documentation prompts are specific about the audience, explicit about assumed knowledge, scoped to a task, and describe anti-patterns, (the things the output should not do).
Here’s the difference in practice:
Weak prompt: “Write documentation for this authentication module.”
Stronger prompt: “Write documentation for a developer who has already set up the project and needs to implement token-based authentication for the first time. Assume they understand HTTP and have seen JWTs before but have never used this specific library. Don’t explain what authentication is or why it matters. Focus on what they need to run and in what order, what the expected outputs are, and what the most common errors look like and how to fix them.”
Yes, the second prompt takes longer to write. That’s the point — that’s where the thinking happens. That’s the work that separates documentation from generated text.
A few practices that consistently improve what AI produces:
Start steps with verbs. “Run the following command” rather than “The following command can be run.” Imperative voice reads faster and is harder to misinterpret.
Name what to skip. If your audience already knows a concept, say so explicitly. “Do not explain what a virtual environment is” is a legitimate and useful instruction. The model will follow it.
Ask for the hard parts. Explicitly prompt for edge cases, common errors, and failure states. These are what users actually need and what AI will omit unless asked, because they’re not visible in the code – they’re visible in user behavior.
One concept per section. Ask the model to structure docs so each section stands on its own. If a concept needs to reference another, a link is better than an inline explanation. This becomes important later for reasons beyond human readability.
The irony at the center of this problem is the same discipline that makes documentation good for human readers also makes it good for AI agents – and agents are now a significant share of who reads your docs.
GitBook reported that AI-driven readership of its hosted documentation increased 500% in 2025, now accounting for 41% of all docs readers on the platform.
When a developer asks their coding assistant how to use your library, that assistant is reading your documentation. If your docs are verbose, repetitive, and poorly structured, the assistant produces, verbose, repetitive and poorly structured answers. The quality problem compounds downstream.
AI agents parse documentation as raw data within token limits, marking markdown 80-90% more efficient than HTML for accurate retrieval. However, formatting is secondary to structure. An AI agent reading your docs is doing the same thing your human reader is doing: trying to extract a specific piece of information quickly. It fails for the same reasons. Inconsistent terminology forces it to guess which term is canonical. Overlong pages get truncated at the context limit, cutting off whatever was at the end. Sections that lead with context before getting to the action bury the useful content.
Nearly half of developers now say they distrust AI output accuracy. A significant part of that trust problem is a documentation problem. The model is only as accurate as the source it’s reading.
A few structural practices worth adopting now:
Use one term for one thing. It’s hard enough to keep track of the ever-shifting glossary of industry terms. Pick it and don’t drift. If your config file is called `config.yaml` in the introduction and `the configuration file` in section three and `your settings file` in the troubleshooting guide, a human reader will figure it out, but an AI agent will not.
Write sections that can stand alone. An LLM doesn’t always read a full documentation set in sequence – it retrieves chunks. A section that only makes sense in the context of the section above it will fail in retrieval. The self-contained section is also, not coincidentally, clearer for the human reader who jumps to the middle.
Action before explanation. Tell the reader what to do, then explain why if it’s not obvious. This matches how both human readers and retrieval systems scan for relevant content.
Consider an `llms.txt` file. It’s become a de facto standard for telling AI readers what to read and how to prioritize – crawled by major models as a structural signal. It’s low effort and meaningfully improves how AI assistants surface your product.
There’s a judgement layer in good documentation that no prompt will produce for you. It’s the decision about what your reader already knows. It’s recognizing that the second step in your getting-started guide is the one where everyone gets stuck, and that two sentences of context there would prevent thirty minutes of troubleshooting. It’s knowing that your API behaves differently in production than it does in development, and that this needs to be said explicitly because it isn’t visible from the code.
That knowledge doesn’t live in your repository. It lies in your team’s experience of watching people fail with it – and it enters documentation through a human being who has the judgment to know it belongs there.
The AI can structure your documentation, generate your boilerplate, write your parameter tables, and draft your examples. What it cannot do is bring the reader into the room. Only you know who that reader is, what they already know, what they’re trying to accomplish, and where they’re going to hit a wall. That knowledge has to enter the system somewhere. The prompt is where it starts. If you skip that step, you get documentation that covers everything and serves no one – organized, complete-looking, and unread.
Technical writing has always been an underappreciated discipline. The people who do it well make invisible decisions on every page: what to say, what to assume, what order things need to appear in, where a reader’s attention will flag and needs to be caught. AI can produce the scaffolding, but it cannot make those decisions without you.
Generated is not written.