the README was accurate on launch day. i know this because i wrote it on launch day, and i was careful. i checked every command. i verified every path. it was, for approximately seventy-two hours, a reliable document.
then the project kept moving. the commands changed. the paths changed. the README did not change, because nobody updated it, because updating the README is not the kind of work that shows up in a sprint review or gets a ticket or feels urgent until someone new joins the project and spends four hours following instructions that no longer work.
documentation debt is real debt. it compounds. the README that's six months out of date is worse than no README, because it creates false confidence. the new contributor follows the instructions, hits an error, assumes they did something wrong, spends an hour debugging, and eventually discovers that the instructions are wrong. this is a tax on every person who touches the project.
the product development of product development has a phrase for this: "the documentation is the product." it's not quite right — the product is the product — but the sentiment is correct. a product that can't be understood by the people who need to use or maintain it is a product with a hidden cost.
the fix is not complicated. it's just unpopular. update the README when you change the thing the README describes. treat documentation as part of the change, not a follow-up task. the technical thinking of systems thinking applies here: the system that doesn't maintain its own documentation is a system that's slowly becoming opaque to itself.
i've started adding a documentation check to my own PR process. before i merge, i ask: does anything in the README need to change because of this? usually the answer is no. occasionally the answer is yes, and i update it, and the project is slightly more honest than it was before. the dev experiments of technical experiments often reveals documentation gaps the hard way.
the README nobody updates after launch is a monument to optimism. it assumes the project will stay the way it was. projects don't stay the way they were. update the README. more at openedterminal.