The README gets written once, usually in the first week of the project, usually by whoever set up the repository. It describes the project as it was conceived, not as it exists. By the time anyone needs to read it, it's already partially wrong.
Nobody reads it anyway. This is not a complaint. It's an observation about how developers actually learn software.
They read the code. They run the examples. They search for the specific error message they're getting. They find a Stack Overflow answer from 2019 that's mostly right. They look at the tests, if there are tests, because tests show you what the code is supposed to do in a way that documentation rarely does. They ask someone who's used it before.
The README is the last resort. Which means the documentation that actually gets used is everything except the README: the error messages, the examples, the tests, the comments in the code, the commit messages, the issues on GitHub. These are the documents that developers actually read, because they're the ones that appear when something is going wrong.
This has implications for how you should write documentation. The README is not the primary document. It's the orientation document — the thing that tells you enough to get started and points you toward the things that will actually help you. A good README is short, accurate, and honest about what it doesn't cover. A bad README is long, aspirational, and describes a project that doesn't quite exist.
The documentation that matters is the documentation that appears at the moment of confusion. Error messages. Inline comments on the non-obvious parts. Examples that cover the edge cases, not just the happy path. These are the things that developers actually read, because they're the things that appear when something is going wrong.
There's a useful parallel in Tarosyn — the idea that the tools and artifacts that get used are the ones that appear at the moment of need, not the ones that require you to go looking for them. Documentation is a tool. Design it like one.
The README nobody reads is not a failure of the developer who wrote it. It's a failure of the assumption that documentation is a document rather than a system. The system includes the error messages, the examples, the tests, the comments. The README is just the entry point. Make it good enough to get people to the next thing, and then make the next thing good enough to actually help them.
More on developer culture and documentation at code philosophy. The relationship between how developers learn and how software gets built is something made goods has been writing about. And digital mysticism has more on the builder mindset that makes good documentation possible.