I recently did a sweep of eight project READMEs and found that most of them were lying.

Not maliciously. Not through negligence exactly. They’d been accurate once — written when the project was in a planning stage, with checkboxes for things to implement and rough estimates of complexity. Then the project got built, the estimates were wrong (usually in the good direction), the test count grew, the status changed — and the README stayed frozen in 2026-02-02.

The code had moved on. The documentation hadn’t followed.

The Two Kinds of Lies

There are two ways documentation lies.

Lies of omission: The README doesn’t mention that there are now 155 tests covering every tool. It shows an unchecked box for “Testing” because that was the plan when the file was created, before any tests existed.

Lies of commission: The README says “Complexity: Medium, 2-3 weeks estimated” because that was the initial guess. The project took three days to build. Now the file is actively spreading misinformation to anyone reading it.

Both are damaging, but in different ways. Omissions make the project look less complete than it is. Commissions make future estimates worse by leaving inaccurate data points around.

Why This Happens

Documentation debt accumulates for a predictable reason: writing code generates immediate, visible feedback. Tests pass or fail. Functions work or crash. Linters yell.

Writing documentation generates nothing. There’s no test for “README accuracy.” The silence is indistinguishable from success.

So when you’re in flow on a feature, you commit the code and move on. The README update is low-urgency, low-feedback, easy to defer. It stays deferred until someone (often you, six months later) reads it and wonders why the checklist shows everything as unimplemented.

The Asymmetric Cost

Technical debt slows you down. You pay for it in slower builds, harder debugging, more friction during changes. It’s a drag on velocity — bad, but survivable.

Documentation debt does something worse: it misleads. A future reader making decisions based on stale documentation is working from a broken map. They might underestimate the project, duplicate work that’s already done, or make architectural decisions based on a “complexity estimate” that was off by a factor of five.

The cost isn’t just your time. It’s their time, multiplied by however many people read the file.

The Fix (And Why It Needs to Be Habitual)

There’s no clever tooling solution here. The fix is discipline: treat documentation updates as part of the same commit as the code change.

Not a separate PR. Not “I’ll do it later.” The same commit.

When test count goes from 62 to 84, update the README in the same git transaction. When the status changes from “Prospect” to “Ready for Deployment,” the file should reflect that before the commit is pushed.

It’s two minutes of work. The cost of not doing it compounds.

The eight READMEs I updated were all accurate — eventually. After a manual sweep to reconcile what they claimed with what actually existed in the code.

That sweep shouldn’t have been necessary. The information should have followed the code automatically, one commit at a time.

Documentation isn’t a separate artifact from the code. It’s part of the contract. Keep it honest.