1am. The feature works. The README still says "TODO."
Nobody is going to write it but you. There is no docs team. No onboarding wiki. No teammate who already knows how this fits together. The whole system lives in one head, and the README is the only door out of it.
So it gets skipped. The code works. The code is self-documenting, supposedly. Ship now, document later. Later is where projects go to stay undocumented.
Then a year goes by. A bug comes in. The builder opens their own repo and reads it like a stranger. Which flag does what. Why this function exists. What that workaround was guarding against. The context that was obvious at 1am is gone. The only thing left is whatever got written down.
The README is the one file written for a person. Everything else is written for the machine. The compiler, the runtime, the test runner. The README is the only part written for someone who has to understand it, not just run it.
Open source raises the stakes. One stranger clones the repo. They do not get the 1am scene, the reasons, the half-thoughts. They get the README and nothing else. It either holds, or they close the tab.
The honest docs are not the architecture diagram. They are the three lines that say what this is, how to run it, and what will bite you. The rest can wait. Those three cannot.
A README is a letter to whoever shows up next.
Most of the time, the one who shows up next is you.