Your README is probably lying to your users
I think documentation is one of the biggest “everyone knows it’s broken, nobody owns it” problems in software.
The code changes.
The README doesn’t.
A setup command becomes outdated.
A new environment variable gets added.
An API route changes.
Nobody notices until a contributor or teammate spends hours debugging something that isn’t actually a bug.
After running into this repeatedly, I spent the last few months building Driftless.
It:
• Analyzes your actual codebase
• Generates READMEs from real project data
• Detects documentation drift automatically
• Alerts teams when docs fall out of sync
• Opens PRs to keep documentation updated
I also built a free README Roast tool that analyzes any public GitHub repository and points out documentation issues. https://driftlessx.dev/#roast
What I’m trying to figure out now:
Is documentation drift a painful enough problem that you’d actively solve it, or is it just an annoyance developers learn to live with?
I’d genuinely appreciate honest feedback from anyone who’s maintained a growing codebase.
Try : https://driftlessx.dev
7 Days free pro trail - cancel anytime.
Direct answer to your validation question, from the buying side: developers treat doc drift as an annoyance and rarely pay to fix it. Engineering managers pay for what it actually costs: onboarding time. Every stale README shows up as a new hire losing their first two days, and that's a line item a manager can justify. I'd reposition around time to first successful setup and sell to the person who hires, not the person who debugs. Your roast tool is the wedge. Run it on repos of teams that are actively hiring and put the results in front of the hiring manager.
This is the most useful thing anyone has said to me since I launched. Genuinely.
You're right and I've been selling to the wrong person. Developer sees documentation drift as an annoyance. Manager sees it as onboarding cost. Those are completely different conversations and completely different budgets.
The roast-on-actively-hiring-repos angle is something I'm going to try this week. That's a warm signal — they're about to spend $80k on a new hire who will spend their first two days debugging stale docs. The math writes itself.
Can I ask — are you on the buying side as an EM or have you seen this from the developer side? Trying to understand whether the manager pitch resonates with people who actually hold that budget.
Yeah I have to say in my experience the past 20 years, readmes have been use full on the first week of employment then never used again after getting local environments setup. If your company doesn't get a lot of new employees it makes sense why it doesn't get a lot of love.
That being said you can probably just have Claud Code or Copilot update it in about 30 seconds so not sure there is much need for a product to do this especially a paid product. Good luck though!
20 years of experience is worth listening to — thank you for the honest take.
You're right that Claude Code or Copilot can generate a README in 30 seconds. That's a fair point and I won't argue it.
The part they don't solve is what happens after.
Nobody opens Copilot and thinks "let me update the README" after merging a PR. It requires a human to remember, prioritize it, and actually do it. In 20 years of software you've probably seen how often that happens in practice.
The value isn't the generation — it's the monitoring. When an env variable gets added, a script renamed, or an API route removed, Driftless catches it automatically and flags it before the next new hire hits it.
You're also right that companies with low hiring velocity don't feel this pain much. That's a real market size constraint I think about.
The target is teams that are actively growing or open source projects with external contributors — where the README is the first thing a stranger sees before they decide whether to use the project at all.
Genuinely appreciate the pushback. This is more useful than encouragement.
Annoyance that compounds. Solo it's manageable, but the moment a second person touches the repo it becomes a real problem. I've lost hours debugging "bugs" that were just stale docs. The issue is nobody feels responsible for fixing it, so it never gets fixed.
Your README Roast tool is the right entry point : low friction way to show people the gap before asking them to pay.
Stale Documentation and Debugging
"Nobody feels responsible so it never gets fixed" — that's the core of it.
With one person, it's manageable because you know the codebase. The moment someone else touches it, your mental model doesn't transfer. The README is supposed to bridge that gap, but it's already out of date by the time they need it.
The hours lost to "bugs" that were stale docs is real and it's an invisible cost — doesn't show up in any ticket, doesn't get attributed to documentation, just looks like a slow onboarding or an unproductive debugging session.
You mentioned low friction entry point — that's exactly what I was going for with the roast tool. No signup, no commitment, just an honest score on what's wrong.
What's the worst stale docs moment you've hit? Curious what the actual debugging rabbit hole looked like — might be useful for how I describe the problem.
Mine is less about solo work and more about teams, and honestly it's the human side of your point. In group projects at uni, and a couple of times in pro settings, there's always that one person who never keeps the README in sync with the codebase. Garbage commit messages, work half-done and marked as finished.
The worst case: the README said a feature was done and working. It had actually been broken three iterations earlier and never updated. Another time the README said a feature wasn't there yet, but it had been built, the person just never ticked it off. So I sat down and reimplemented a feature that already existed. Hours of work, completely wasted, because the doc was describing a reality that didn't match the repo.
That's the brutal version of your invisible cost: it's not even slow debugging, it's straight-up duplicated work. And it never gets attributed to documentation, it just looks like someone being inefficient.
The pattern underneath it is what you nailed: nobody owns the README, so it drifts to whoever cares least. In a team that's always the weakest link, and everyone else pays for it silently.
The duplicated work example is especially interesting because it’s not the kind of cost people usually attribute to documentation. Nobody opens a ticket saying “the README caused this", they just lose hours building or debugging the wrong thing. That’s exactly why I think documentation drift is easy to underestimate until you’ve experienced it firsthand. Thanks for sharing those examples.
Exactly. The invisible part is what makes it so hard to fix, there's no metric that ever points back at the doc. Glad the examples landed.
I think documentation drift is a real problem, especially in larger projects. For small teams it's often something people just live with.
The README Roast is a smart idea though. It immediately shows the value of the product.
How accurate is the drift detection in real-world projects?
Honest answer on accuracy:
For the signals it tracks deterministically — env vars, scripts, dependencies, API routes — it's highly accurate because it reads actual files, not descriptions. If you add STRIPE_SECRET_KEY to .env.example, it catches it every time.
Where it's imperfect: it can miss semantic drift. If you rename a function but the interface stays the same, it won't flag it. It catches structural changes, not logic changes.
For small teams, you're right — people live with it. The product makes more sense the moment a second person touches the repo and hits a broken setup instruction.
The Roast tool is the honest way to show accuracy — paste any public repo and see what it finds. Happy to run it on one of your projects and walk you through what it detected vs. what's actually in the codebase if you want a real test.
What kind of projects do you work on? Would help me understand if the current detection covers your stack.
For context I work mostly on smaller client projects — WordPress, Next.js, custom builds. Not the biggest repos but documentation drift still hurts when you hand something off to a client.
Funny timing actually — I just launched something in a similar spirit. knallhart[.]dev roasts websites instead of READMEs.
Same idea: brutal honesty about what's broken, delivered fast.
Might be interesting to cross-promote at some point — different layer of the same problem.
That’s a great use case I hadn’t thought enough about. Client handoffs probably make documentation drift even more visible because the person receiving the project doesn’t have the context gaps filled in. Also love the similarity between our products—different layers, same goal of exposing hidden issues early. Congrats on the launch! 🙌
Exactly — the handoff moment is brutal. Everything that "everyone knows" suddenly has to be written down, and that's when you realize how much was never documented.
Thanks! Would be cool to stay in touch — two tools attacking the same problem from different angles. Maybe there's something in that at some point.
Yupp!! thanks for the conversation and good luck with ur launch!
I’ve hit this building my open-source tools - contributor burned by stale setup docs, fixed them, then let them drift again. nobody owns the refresh cadence. auto-generating from the actual codebase removes that ownership problem.
This is exactly it — "nobody owns the refresh cadence" is the most accurate description of the problem I've heard.
I kept seeing the same pattern: contributor gets burned, fixes the docs, merges the PR, then the next 10 commits quietly break them again. The fix doesn't stick because there's no mechanism to detect when it breaks.
That's what drift detection tries to solve — not the one-time fix, but the ongoing monitoring so you catch it before the next contributor does.
How many contributors does your project have? Curious whether drift gets worse linearly with team size or if there's a tipping point.
yeah that's the second-order problem - the fix creates a false sense of safety. only sticks when the docs structurally can't diverge from the source.
Exactly. A README update is a point-in-time fix. Without a feedback loop, drift becomes inevitable. The more I talk to people, the more I think the real problem isn't documentation quality—it's the lack of a system that tells you when documentation stops matching reality.
Ufff, diste en el clavo. Pasamos más tiempo del que me gustaría admitir solucionando problemas que resultaron ser un setup obsoleto en el README. Es un problema real y doloroso cuando el código se mueve rápido. ¡Voy a probar la herramienta gratuita de 'README Roast' con uno de mis repositorios públicos a ver qué tal está! Gran iniciativa
¡Te lo agradezco! Ese es precisamente el problema que intento resolver. Todo funciona bien hasta que alguien sigue unas instrucciones que eran correctas hace unos meses. Me encantaría conocer tu opinión después de probar la herramienta Roast.
This is a real problem that a lot of teams run into. The codebase evolves quickly, but documentation almost always falls behind. I’ve personally spent hours debugging things that turned out to be just outdated instructions in the README.
I like the idea of automatically detecting drift and opening PRs — feels like a practical solution.
Quick question: how well does Driftless perform across different tech stacks? For example, does the quality of the generated README vary significantly between a simple Node.js project and more complex full-stack applications?
Also curious about your thoughts on AI-assisted documentation in general. I’ve been using agents like Cursor quite a bit lately, and I’ve found that they can already produce surprisingly good READMEs when you give them enough context from the codebase. Do you see Driftless as something that goes beyond what current AI coding agents can do, or is the main value more in the continuous drift detection and automated PRs?
Great questions — honest answers:
On tech stack coverage:
Works well out of the box for Node/TypeScript, Python (FastAPI, Django, Flask), and most standard web stacks. It extracts scripts, env vars, and dependencies locally before any AI call — so those are always accurate regardless of stack.
Where it struggles: monorepos with unusual structures, heavily custom build systems, or repos with no .env.example. Multi-service repos (Python backend + React frontend) work but need the services to be in predictable directories.
On Cursor vs Driftless:
Honest answer — Cursor can generate a great README if you prompt it well and give it context.
You're right about that.
The difference is two things:
1. Cursor requires a human to remember to do it.
Nobody opens Cursor and thinks "let me update the README" after merging a PR. It's always someone else's job
2. Drift detection is the actual moat.
Cursor generates once.
Driftless monitors continuously — when you add an env var, rename a script, or remove an API route, it catches it automatically and can comment on the PR before anyone merges.
The value isn't really "better README generation than Cursor."
It's "your README stays accurate without anyone remembering to maintain it."
Different problem than what Cursor solves.
Free roast tool if you want to test accuracy on your stack: https://driftlessx.dev/#roast
Happy to generate a sample for any repo you want to test with.
This hits a real and often overlooked problem. Documentation drift rarely feels urgent, but the cumulative cost across teams is significant. I like the shift toward treating docs as a reflection of the codebase rather than something manually maintained.
Automating detection and updates makes a lot of sense, especially as systems grow more complex. If the signal stays accurate and low-noise, this feels like something teams would quickly rely on. Overall, this is a solid and practical approach to a problem most teams quietly struggle with.
Thank you! That's exactly the direction I'm aiming for. Documentation drift is usually a slow, compounding problem, and my goal is to make docs a reliable reflection of the codebase rather than a manual responsibility. Keeping the signal accurate and low-noise is definitely the key challenge.
Interesting space.
The thing I'd be careful with is that some problems look obvious once you've lived with them for years.
The harder part is deciding whether the market experiences the problem the same way you do.
That's one of those decisions that can quietly shape everything that follows.
I wouldn't make that call casually in a thread.
Completely agree. That's actually one of the main things I'm trying to validate right now—whether documentation drift is a niche frustration or a problem teams actively want solved. Appreciate the insight.
Possibly.
The reason I stopped short is that the useful part isn't the validation itself.
It's the decision that follows from it.
I wouldn't unpack that casually in a thread.
If you'd like the tighter version, drop your email and I'll put it together properly.
Interesting point. I'd actually love to hear the high-level takeaway here if you're willing to share it publicly. I suspect others following the thread would benefit from it too.
Possibly, but that's exactly why I stopped short.
The useful part isn't the takeaway itself.
It's understanding what decision that takeaway would actually lead you to make.
That's the part I'd be careful discussing casually because it can send the business in very different directions.
If you'd like the tighter version, happy to put it together properly. Just drop your email.
That's fair. I think I've got the gist of the distinction you're drawing. The next step for me is getting more signal from users and seeing what decisions that actually points toward. Appreciate the discussion.
This comment was deleted 3 months ago
Nice concept! Gotta try on my project
Thanks! Try: https://driftlessx.dev
7 days free pro trail.
and if u signup today u will get extra 25% off on pro/team after your free trial ends.
try now 🚀
Great product!
Documentation drift is one of those annoying problems nobody talk about enough. Intresting approach to solve it.
Tested it on one of my GitHub project the generated Readme was surprisingly accurate!!
Thank you! Really glad to hear that. The goal was to make the generated README reflect what's actually in the codebase rather than relying on generic templates. Feedback like this gives me confidence that I'm solving a real problem. Appreciate you taking the time to test it
Nice Product , that’s exactly the problem developer faces everything works fine early on, but as projects evolve, docs tend to fall behind the code.
good luck with your launch.
Thanks! That's exactly the pain point. Documentation usually starts accurate, but every small change creates a gap between the code and the docs. Driftless is my attempt to close that gap automatically.