The README lies.
Not on purpose. It was true the day someone wrote it. Then the function got renamed, the flag got removed, the env var changed, the endpoint moved — and nobody touched the docs, because nobody's job is the docs. So the README quietly drifts away from the code, and the first person to find out is whoever copy-pastes the snippet that no longer works.
If you've ever opened a doc page, scrolled to a code block, and thought "...is this still real?" — you already know the failure mode. Docs don't rot because people are lazy. They rot because keeping them in sync is manual work that lives outside the loop where the change actually happened.
The insight: docs are a side effect of merging code
The diff already knows everything. When you merge a PR, the change is right there — the renamed function, the new param, the deleted flag. That's the exact moment the docs should update, and it's the exact moment everyone is busy doing literally anything else.
