Vibe-Docs: Documentation Won't Make It

I'm just going to say it: traditional documentation is becoming obsolete, and pretending otherwise is a waste of everyone's time.

I don't write much documentation anymore. I write ADRs when we make moderate to big decisions, and I take notes on non intuitive business logic. That's about it.

The Reality Check

Here's what actually happens with documentation in 2025, and actually all the years before:

You join a new project. There's either a 50-page Confluence wiki that was last updated 8 months ago - half the links are broken, the setup instructions reference services that don't exist anymore. You spend 2 hours reading it, then another 3 hours figuring out what's actually true. Or, in even more cases, there is no documentation to speak of.

What you're probably doing instead: You paste the repo into an AI and ask "how does authentication work here?" You get an accurate answer in 30 seconds. Granted, not always 100% accurate, but at least as accurate as the outdated docs.

The Documentation Lie

Let's be honest about why documentation is always outdated: nobody has time to write it, and even fewer people have the patience.

You ship a feature. You're supposed to update the docs. But you've got three other tickets waiting, a production issue to investigate, and honestly? You know nobody reads those docs anyway. So you skip it. Everyone skips it. The docs rot.

It's not laziness - well maybe a little. But it's reality. Documentation is maintenance overhead that competes with actual work, and actual work always wins.

The old argument was "future you will thank you for writing docs." But future me has Claude. They will be fine.

What Changed

AI can read code faster and more thoroughly than any human. It doesn't get bored. It doesn't skip files. It can trace through call stacks, understand dependencies, and explain complex flows without breaking a sweat.

More importantly: AI reads the actual current state of your code. Not the aspirational version from 6 months ago when someone had good intentions about keeping docs updated.

This is what I mean by "vibe-docs". Not using AI to write documentation (though that works too), but replacing documentation entirely with source code + AI. Your codebase becomes the single source of truth, and AI becomes the interface for understanding it.

It's always current because it's reading what actually exists. Not what someone remembered to document.

What Actually Matters Now

That is why i think the bar has shifted. Instead of documentation, we need to focus on:

Business context that AI can consume. Keep lightweight markdown files that explain domain logic, business rules, and constraints. Not how the PaymentService works, but why payments can't be processed on weekends, or why refunds have a 90-day window. AI can read these alongside your code to give accurate answers about behavior.

The why, not the what. AI can figure out what your code does. It can't figure out why you made certain architectural decisions. That // Using eventual consistency here because of X requirement comment? Still valuable. Your 3-page document explaining what the UserService class does? Completely redundant.

Decision logs. When you chose PostgreSQL over MongoDB, when you decided to use microservices, when you picked Kubernetes over ECS—those decisions and their context matter. The implementation details? Less so.

ADRs will always matter. Business logic context will always matter. But explaining how the code works? That's what the code itself is for.

What About Onboarding?

"But how will new developers learn the system?"

The same way they do now, except faster. They'll ask questions. Except instead of asking a senior dev or reading stale docs, they'll ask AI. And they'll get instant, accurate enough answers about the current codebase.

The Uncomfortable Truth

A lot of documentation was always performative anyway. We wrote it because we thought we should, because it seemed professional, because some process demanded it. Not because it was actually useful.

How many times have you written docs that nobody read? How many times have you skipped reading docs and just looked at the code? How many times have docs been wrong and caused more confusion than clarity?

And honestly, who has time to maintain comprehensive documentation? Even if you wanted to, you'd need to update it every time the code changes. Every refactor. Every new feature. Every bug fix that changes behavior.

If AI can answer questions about your codebase accurately and instantly, what's the actual value of maintaining parallel documentation that will inevitably drift out of sync?

The Bottom Line

Documentation was a solution to a problem: how do we transfer knowledge about complex systems? That problem still exists. The solution has just changed.

We've moved from "write it down separately" to "make the source itself understandable." Not through comments and docs, but through clarity + AI-assisted reading.

Fighting this shift because "that's not how we've always done it" is pointless. The AI can read your code better than any human will read your docs. Maybe it's time to stop pretending otherwise.

Write clean code. Document your decisions. Let AI handle the rest.