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 (10)
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!
"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.
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. 😂
Thank you for sharing such an excellent post. I really enjoyed reading it.
I’m a Python Full-Stack Engineer with over 10 years of experience designing and building scalable software solutions for clients across a variety of industries. Along the way, I’ve learned that successful projects depend not only on strong technical execution but also on creating real business value.
With my recent contract completed, I’m exploring new opportunities to collaborate with professionals who value innovation, practical problem-solving, and long-term partnerships. I enjoy discussing ideas that combine technical excellence with sound business strategy, creating outcomes that benefit everyone involved.
I believe every connection has the potential to become something meaningful. If you're interested in exchanging ideas, exploring opportunities, or simply connecting with someone who enjoys building impactful technology, I'd be happy to hear from you.
Wishing you success in your future endeavors, and I look forward to connecting.
If you allow me, I wanna discuss about collaboration and income.
Well said — especially the "how vs. why" distinction. That intent gap is the hardest thing to encode, and most people pretending docs are dead are conveniently ignoring it.
Been thinking about this a lot while writing the 36 Stratagems series. One thing that keeps surfacing: almost every protagonist in these stories carries a notebook — not a shared Notion, not a README. Just their own records, screenshots, timestamped logs. Because by the time they need to prove why a decision was made, the code already moved on. That gap is real.
"Don't delete your markdown files" — yeah, that's going on a sticky note.
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.
You made a valid point, Ben. AI has a limitation. We have a Canadian startup company by the name of Backboard IO in Ottawa. The company is fixing the situation in AI. I don't any other Canadian companies are working on the situation by heart.
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.
Some comments may only be visible to logged-in visitors. Sign in to view all comments.