There is a growing sentiment in engineering circles right now that documentation is a relic of the past. The argument usually goes something like t...
For further actions, you may consider blocking this person and/or reporting abuse
"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.
The strongest point here is that AI makes documentation more important, not less.
If a model can generate plausible code quickly, the scarce thing becomes shared intent: why the system exists, what tradeoffs were accepted, which paths are dangerous, and what future maintainers should not casually undo. Without that, the model can move faster while inheriting less context.
Strong agree with the premise. AI does not remove the need for documentation. It raises the cost of vague documentation.
When humans read docs, they can often infer missing context from team history, product intuition, or “that sounds wrong.” Agents do not have that same guardrail unless the docs give it to them.
The documentation that matters more now is:
The mistake is treating docs as prose for humans or chunks for retrieval. Good docs are interface design for both humans and tools.
If anything, the post-documentation era is just the end of decorative documentation.
I am definitely a "the code should be doing the heavy lifting of documentation".
I am a big proponent of writing documentation at specific code points, where the why is unclear, or something written for speed, and not part of the normal approach to code, exists. For example: I do alot of functional programming paradigm, but there are certain times one would need to break out of that, to get the necessary speed, or memory reduction. Great time for comments. Like you said, why. "Why is it this way?" That normally pre-supposes, there are other normal ways (within this codebase) of doing something, but this is different. Why?
I'd also say that everything higher level than "what is this actually doing", should be documented with some level of prose. Moving from high level into the details.
I absolutely 100% hate, with an epic passion, documentation that AI just willy nilly throws in. (Usually inline code level documentation).
I dont know if wit hthis comment I'm gonna agree or disagrree, but this debate, is similar to a time when C lang appeared, and compilers that translates a more human readable programming language to a machine code.
Wghen you say slope translates slope, is basically the same shift. We have a tool that translates human natural language into a human readablee programming language.
It's jsut a matter of perspective. But the whole article is super interesting and I'm glad you talked about it because I tthink about it "philosophically" every day.
The "intent gap" framing here is sharp. I've been thinking about this in the context of AI-generated code â when you ask an LLM to implement something, it produces syntactically correct, logically sound code. But the code can't explain why the original engineer chose this trade-off over that one.
This is where prose docs genuinely earn their keep, even in an agent-driven world. A function can be self-documenting about what it does, but the why of architectural decisions â why this cache eviction policy, why these retry semantics, why this error boundary here and not upstream â lives in a different layer entirely.
One thing worth adding: the problem gets harder when docs drift from code. If the AI is reading stale documentation and then generating code that contradicts current behavior, you've created a new failure mode that pure code reading wouldn't have.
What's your take on the documentation that matters most for downstream AI consumers â high-level architectural narratives, or detailed behavioral specs?
I've been working on the practical implementation of exactly this problem and it's a pain point I kept hitting across every project. A few months ago I published an open-source memory layer called Zerikai Memory that indexes a codebase into a local vector store and makes it queryable by any IDE agent. The intent gap you describe is what the project brief solves. On every scan it synthesizes a structured brief from the indexed codebase covering architecture, data flow, trade-offs, routing decisions. Not just what the code does, but why it's shaped the way it is. That brief becomes the fixed prefix on every LLM query so the agent is working from actual context instead of guessing from raw syntax.
The "slop describing slop" section hit close to home. The system has an Embedding-Docstring skill that audits every function, class, constant, and HTML boundary element against a density checklist: technology names, routing logic, guarantees, side effects. It proposes before/after diffs and nothing gets written without explicit approval. No blank checks to the LLM. On the trust and reputation problem, I don't think anyone has cracked that yet, but every query response surfaces a file and line citation with a distance score showing how closely the retrieved entity matched the query. It's not a reputation system. It's a measurable signal per answer rather than a vague assurance that someone looked at the docs once.
Things get absorbed, layered over, automated, or narrowed in scope. Documentation isn't dying; the part of it that was busywork is getting offloaded.
The post-documentation idea breaks down as soon as you need shared memory across time. AI can summarize what exists, but it cannot replace the decision record that explains why the system is shaped that way. The best docs are not prose for its own sake; they are durable context that prevents every future agent or teammate from rediscovering the same boundary.
Documentation was always a lossy compression of decisions that lived in people's heads. AI didn't create that gap, it just removed the excuse that the code is self-documenting, because now the thing reading the code for context has even less access to the why than a new hire would.
The “intent gap” framing is the part that matters most here. Code and specs are good at describing the executable surface, but they are usually terrible at preserving the tradeoff history that explains why a boundary exists or why an ugly edge case stayed ugly on purpose. I also agree that the failure mode is not “generated docs,” it is unreviewed generated docs that become a second layer of drift. In practice I’ve found the best pattern is keeping human-written intent close to the code path and letting automation help with freshness, not authorship. Curious whether you think trust in docs will come more from stronger review workflows, or from better provenance and reputation signals around who or what produced each section.
From my own experience, I know how hard it is to gather good context for an AI agent system. Just scanning the codebase isn't enough — it leaves hidden architectural decisions and trade-offs out of the picture. Not to mention, it's just more expensive. As a result, you get low pipeline efficiency and wasted tokens.
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.
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.
Great points about documentation in the AI era. In my experience, the key is balancing AI-generated docs with human review — the context awareness that experienced developers bring is still hard to replicate.
Interesting perspective. One thing I'd add is that context matters a lot here — the right approach depends heavily on team size, project stage, and existing infrastructure. There's rarely a one-size-fits-all solution.
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.
Appreciate the practical approach here. The real test of any pattern is how it holds up over time — would be interesting to see a follow-up covering how this has scaled as the project grew.
If you're going to save 90% of your time, letting AI write it for you. The least you can do is take the time to document it...