Lesson 88: README & Documentation
The junior trap
Picture a fresh grad joining your team. Their first task: add a test suite to a service, then write a README so the next person doesn’t have to ask them how to run it. Here’s what that README usually looks like:
## Setup
pip install -r requirements.txt
pytest
Four lines. It looks done. It is not done — it’s a guess dressed up as documentation.
The problem isn’t that it’s short. The problem is that nothing checks whether those four lines are still true. Three weeks later, someone adds a new environment variable the tests need. Two months later, someone renames requirements.txt to requirements-dev.txt. Six months later, the CI image switches from Python 3.9 to 3.11 and a dependency stops building on it. Every one of those changes is reviewed, tested, and merged — and the README is untouched, because nothing in the pipeline treats English sentences as something that can fail.
This is the same mistake as time.sleep(5) in a UI test. A junior dev sees a flaky test, adds a fixed delay, and the test goes green — for now. It “works” the same way that four-line README “works”: it happened to be true at the moment someone looked at it. Neither one is verified. Both quietly rot the instant the system underneath them changes, and nobody finds out until a new hire loses an afternoon to it, or CI goes red for a reason that has nothing to do with the code.
The failure mode: silent documentation drift
There’s no exception traceback for a wrong README. That’s what makes it worse than a flaky test, not better. A StaleElementReferenceException at least announces itself. A stale README just sits there, confidently wrong, until:
A new developer follows it exactly, hits an error the doc doesn’t mention, and assumes they did something wrong.
CI passes locally but fails in the pipeline because the README never documented a required system package.
The “Troubleshooting” section becomes an oral history — tribal knowledge passed in Slack threads instead of version control.
Teams call this “onboarding friction” and treat it as a people problem — better mentoring, more pairing, a Notion page nobody updates. It’s not a people problem. It’s a testing gap. You wouldn’t ship a function with no test coverage and call the resulting bugs a communication issue. A README is a function too: input is a fresh checkout, output is a passing test suite. If nothing exercises that function, of course it breaks.
