How AI is Changing Engineering Docs 📑
A practical guide on how to think about docs in the age of AI.
Here's a thought experiment: tomorrow morning, an AI wakes up with perfect knowledge of every programming language, framework, and design pattern ever created. It can read any codebase, understand any system, and generate any documentation you ask for.
What happens to all the docs we've been writing?
This isn't science fiction — we're already halfway there. AI can parse most codebases in seconds, explain complex algorithms better than most humans, and generate API docs that would take days to write manually.
Which brings us to an uncomfortable question: if AI can understand code without docs, and can write better docs than most humans... what's the point of documentation anymore?
The answer, it turns out, is more complex than you'd think.
We're witnessing a fundamental rewiring of how engineering knowledge works. What we write, how we write it, who writes it, and even why we write it at all.
Now, if you ask me, it was about time. The stats about the effectiveness of developer docs have always been grim:
64% of developers spend over 30 minutes daily searching for information
26% waste more than an hour
That's weeks lost every year, and it has always been hard to figure out why:
Some teams get there because of little to no docs, and overly relying on tribal knowledge.
Others literally drown in docs — Confluence pages, READMEs, Slack threads — and devs can't reliably find what they need.
So the issue isn't strictly quantity — it’s about the whole lifecycle: from recording the right things, to retrieving them at the right time, to keeping them up to date.
This is where AI has the potential to change everything, even if we are still figuring out how.
Today we’ll dive deep into this transformation. We'll explore why AI makes some documentation obsolete while making other types more crucial than ever. We'll examine how teams are already adapting their workflows, and what the future of engineering knowledge looks like when AI can understand your codebase better than you do.
To help me with this, I am bringing in Dennis Pilarinos, founder of Unblocked, who I interviewed just recently on the podcast. Dennis has worked on dev tools his whole career, from holding Director roles at Microsoft and Amazon, to founding Buddybuild (and selling it to Apple), to now building Unblocked.
We touched on some of these topics during our chat, and it was so enlightening that I thought we should absolutely write a full piece on it!
So here's what we'll cover:
🔍 The 30min search problem — why traditional docs fail despite our best efforts
🤖 The AI docs paradox — how AI both needs docs and makes them obsolete
🔄 A new docs workflow — reimagining writing, reading, and maintaining docs
🔮 The future of docs — what engineering knowledge looks like in 2026 and beyond
Let's dive in!
Disclaimer: I am a fan of what Dennis and the team are building at Unblocked, and I am grateful they partnered on this piece. However, I will only write my unbiased opinion about the practices and tools covered here, including Unblocked.
🔍 The 30min search problem
Let's start with a familiar scene:
Sarah, a senior engineer, needs to understand how the payment processing service handles refunds. Twenty minutes later, she's opened various pages on Confluence (”is this up to date?” she wonders), searched on Slack, checked Github READMEs, and scanned PR comments (just joking — who has the time to do that?!)
Finally, she DMs Tom: "Hey, quick question about refunds..."
Tom is a good guy: he answers within a few mins, points her to the one good page in the docs (”this is up to date, scrap the rest”) and gives her additional context that was not written anywhere.
Versions of this happen every day in all the teams I know. Sometimes it’s better, sometimes it’s worse, but I have never found a team that solved documentation.
But why? In my experience, docs have three main failure modes:
They don't exist — writing docs is nobody's job and everybody's job. The people who know the most have the least time, and writing stuff is hard. Trust me, I am a writer.
They can't be trusted — once developers get burned by outdated instructions, they develop a simple heuristic: when in doubt, ask someone.
They can't be found — there is an overwhelming variety of knowledge that potentially deserves to be recorded (ADRs, runbooks, design docs, meeting notes). Good luck finding a universal way to organize it.
Now, even when you do somewhat well on these, the final nail in the coffin is the colleague test: is finding and reading docs faster and easier than asking a colleague?
Quick math:
Reading docs — 20 minutes of focused effort for finding the right stuff + extracting the exact bits that you need.
Slack to Tom — 3 minutes, direct answer to your question, zero cognitive load.
Tom is just too good.
This creates a devastating feedback loop: asking co-workers is easier than using docs → docs get ignored → docs become outdated → trust erodes even more → people stop writing docs.
In the long run, this creates obvious problems:
Tom spends a lot of time answering the same questions over and over, taking it away from productive work. And the paradox is: the better an engineer you are, the more you’ll get questions from others. So it’s your top performers who suffer the most.
Tom eventually leaves the company. During his notice, he hastily writes some notes about the systems he knows best, which nobody will truly understand.
Complex systems for which tribal knowledge has left the company eventually turn into technical debt: they will either swamp productivity or need to be rewritten.
In theory, we have all the pieces of the puzzle to do things better. Over the years we've figured out many smart formats, created good templates, and frameworks for better organization.
Still, getting docs right is an uphill battle: it takes time, effort, and as soon as you lose your grip a bit, things go downhill incredibly fast. It’s a war many teams are losing every day, and not because they are not trying.
So it is fair to say we need rescue, and the bet is that AI is coming for it 👇