There is a growing sentiment in engineering circles right now that documentation is a relic of the past. The argument usually goes something like this: We’re living in the era of agent-driven development. If an AI agent can read the raw source code or parse an OpenAPI specification instantly, why waste human engineering hours writing prose? Code churns too fast anyway, and human-written docs are outdated the second they’re committed.
It’s an attractive, black-and-white view of the world. It’s also completely wrong.
Chasing strict determinism in your source of truth is a pipe dream. Code and specs tell a system how something works, but they are fundamentally incapable of explaining why it was built that way in the first place.
The Intent Gap: Why Code Isn't Enough
Even if you’re building entirely for a downstream consumer of AI agents, there is a massive, structural gap between a raw API specification and an operational reality.
Agents are phenomenal at pattern matching and syntax execution, but they struggle with architectural philosophy and human intent. We still need words to contextualize the boundaries. A spec can define an endpoint, its parameters, and its payload. What it can't capture is the nuance of why a specific architectural trade-off was made, or the implicit historical context of a legacy edge case.
Prose provides the guardrails for non-deterministic systems. Even if that prose is ultimately consumed by a machine rather than a human, the written word remains the highest-leverage way to transmit intent.
The Danger of Slop Describing Slop
This doesn't mean we need to return to the days of manually maintaining massive, static wiki pages. Automation has a massive role to play here. Cascading automation—where documentation is dynamically generated alongside code changes—is incredibly powerful.
But there’s a trap here: slop describing slop is entirely useless.
If we completely hand off documentation generation to unchecked LLMs, we end up with a feedback loop of hallucinated context describing rapidly shifting code. It creates noise, not clarity.
The Key is Oversight. Even if the documentation is entirely bot-driven, human engineering oversight is non-negotiable. We need to gut-check and validate the generated prose to ensure it represents an accurate, high-level explanation of the broader context. Think of generated docs as a non-deterministic cousin of the API itself—highly valuable, but only if kept on a tight leash.
The Trust Crisis and the Search for Reputation
Right now, the single biggest blocker to this new paradigm is trust. The current lack of a "gut-check" trustworthiness metric for documentation is a massive bottleneck for both human developers and autonomous agents.
In the open-source eras of the past, we relied on crude but effective reputation proxies. If a repository had 10,000 GitHub stars, a vibrant issue tracker, and recent commits, you could reasonably assume the project (and its documentation) was stable.
We don't have a reliable reputation system for the AI era yet. The absolute novelty of the moment, combined with how incredibly easy it is to game automated metrics, means everything feels a bit unanchored.
The next major shift in developer tooling won't just be about making agents faster or code generation cleaner. It will be about solving the reputation problem—building systems that can automatically verify, score, and guarantee the trustworthiness of the knowledge bases our software relies on.
Until then, don't delete your markdown files. The machines still need to read between the lines.
Top comments (39)
"Documentation is a relic of the past" is crazy. We NEED documentation to know how things work and being able for others to know how things works to begin with.
Exactly. We need people like @klaudiagrz to still be here. If we rely, we become dependent on it. If we become dependent, we lose our sight of the picture of what code is being run.
Thank you, @francistrdev, for the ping 🙂
If anyone thinks documentation is a relic of the past, they for sure never worked as an operator, trying to fix a production issue at 2 AM, but only having generated content at hand.
As a technical writer, I have seen lots of content so far, both generated and manually written, and I can honestly say I have never seen good generated content so far. It always requires lots of human intervention; otherwise, it's just a slop pretending that there is some documentation, but only creating content debt as a result.
Thank you, @ben, for pointing this out. This "feedback loop of hallucinated context" that you described is a real issue nowadays. I wonder when people will start to realise that 🫥
This is exactly what I've been thinking but couldn't articulate. The post-documentation era myth assumes that AI can replace understanding with answers. But answers without context are just fragments. Documentation is the context.
AI can tell you how to use an API It can't tell you why the architecture was designed that way what the trade-offs were or what not to do. That's where documentation lives.
The more capable AI becomes, the more valuable documentation becomes - not less. Because the AI needs something to be trained on, and humans need something to understand the decisions that aren't in the code.
Thanks for saying this out loud. Needed to be said. 🤝
Especially human written docs!
I kind of like my markdown files! Sometimes there is 20! I like to know what chaos has ensued. I like to hold AI accountable for its steaming pile if it creates one. "Look what you did, sir. You just lied. Bad robot." Its entertaining on some level. I think what everyone needs to accept really, and what you hinted at here, is that we are all still learning how to navigate ai. People that have been coding since before y2k and newbies - all learning and making mistakes together. You know what that means. We get to live during a massive tech revolution. Kind of exciting. A bit scary, but massive lessons and opportunities. Its funny I read this because I was just thinking to myself "if I see one more post about ai slop...." then you talk about feeding slop back to the slop from whence it came. New entertainment. Thanks for that. 😂
Me too! I've been working on some custom agent-agnostic skills for formatting all decisions made (ADR style) into simple markdown files that live alongside the code. I even published a local web dashboard to npm that lets me view everything in the logs without installing anything (via npx).
It's been super helpful for my work lately, but I'm still working on making it better. So far I've used it for everything from my solo dev projects, to capturing info from team meetings held in my dev job (by dumping things like meeting transcripts and slack threads into my "capture" agent skill). It's really amazing being able to ask "why did we write the code like this?" or "What's the status on this feature?" and have my coding agent respond with dated, tagged receipts and cliff notes citing every single time we discussed or worked out a solution.
yes! I like this idea - using the markdown files so you can ask your custom agent about your particular situation. I think that's useful.
I'm working on a codebase, written by 2 people who don't have software engineering experience. The codebase, does NOT do alot, and yet, it was loaded with so many files it is unbelievable. I think there are 400 markdown files. So I ran script to figure out how many lines and then how many words the markdown "documentation" files had in it.
It had MORE prose than the entire Lord of the Rings trilogy. All combined.
Everytime one of those people said "there is a doc on that", I'd give him the evil eye through the computer.
XD
Ben, honest confession: I'm not good enough to not read the code. I suspect most of us developers are in the same bell-curve boat.
The "agents can just read the source" argument assumes a fluency most of us don't actually have on someone else's codebase at 2am. Prose is still how the why gets into my head before the code does. Maybe the people pushing post-documentation hardest are the ones who never needed the docs to begin with . everyone else is just quietly still reading.
The slop-describing-slop failure mode is the sharpest part of this, since generated docs drift the same way generated code does but nobody scores them. What has actually worked for me is treating docs as an artifact with pass/fail checks, running the prose against the current code and flagging any claim that no longer holds before it merges. The trust metric you want probably has to be measured that way, per document, rather than inferred from stars or commit recency.
I've found that AI actually exposes bad documentation faster. If the docs are outdated, the generated answers become confidently wrong.
The "post-documentation era" doesn't exist—it only changes what great documentation looks like.
Code explains how. Documentation preserves why. AI needs both.
Excellent perspective, Ben.
Agree on not deleting the markdown, but I'd sharpen the risk. A stale doc is worse than a missing one, because the agent trusts prose over code. Give it a wrong README next to the right source and it usually follows the README. And the "why" you're defending is the part that rots fastest, since intent gets written once and never revisited. So the real work isn't writing more docs, it's treating them like code: version the why, date it, and make it obvious when it's describing a decision from six months ago instead of the system today.
"Treating them like code" is not how I would describe it, but you are right: documentation (and for me that includes analysis and design documents, bug reports, feature requests, manuals, etc. ) should be versioned in parallel with the code - I already wrote about this in 2013 on my blog (see nukleos.wordpress.com/2013/11/07/b... ), although that was in a more general view of content management systems.
Fair correction, "versioned in parallel with the code" is the sharper framing than mine, and your 2013 point is the one that matters most now: the version a doc forked from isn't the chronologically previous one, so a linear history isn't enough. That maps straight onto the agent problem. A dated doc still doesn't tell the agent which code state its "why" was actually true for. What you were describing for ECM, branching and lineage instead of a linear timeline, is exactly the missing primitive: bind each doc's why to the commit it describes, so staleness reads as measurable divergence from the code rather than something you infer from a timestamp. You were a decade early.
When it comes to coding, I always prefer to add "comments as documentation" to the code - that way they stay with the code when versioned. But that does not work in ECM, sadly...
And there's the obvious requirement: you have to keep the comments in sync with code changes all the time. Which many developers find quite difficult.
That last line is the crux, and it is where the agent angle loops back. Comments living next to the code is the right instinct, but "keep them in sync" is a discipline, and disciplines decay the moment they stop being enforced. The version that survives is the one a machine checks: a comment claiming a function returns sorted output, with a test that fails when it does not, is a comment that cannot silently go stale. Prose you have to remember to update rots; a claim wired to a check corrects itself. Same reason I trust an eval set over a design doc. Enjoyed this one, Wouter.
I'd say the contrary is actually true: they way to control what AI does in a consistent way is through detailes Specs of the work to perform (a good example is SBD, Spec Based Development). In other words, we need the documentation to provide the AI context for the task at hand, so we get predictable and consistent results. So no, not a thing of the past.
Totally agree. AI is great at reading code, but code doesn’t always explain the story behind the code. The “why” is usually where the real engineering knowledge lives.
I think we’re moving toward a hybrid future: AI helps create and maintain docs, but developers still need to review and provide context. Otherwise, we’ll just create AI-generated noise on top of messy code 😄
Also, sharing knowledge through developer marketplaces and communities like codecan.net can help people learn from existing projects and avoid repeating the same mistakes.
Some comments may only be visible to logged-in visitors. Sign in to view all comments.