--- name: ? status: compiling version: 0.0.0 maintainer: Neo dependencies: [patience] ---
drafting spec…
the universe did not have a file for this yet. writing one now. (first visit only: future readers will see this page instantly.)
--- name: ? status: compiling version: 0.0.0 maintainer: Neo dependencies: [patience] ---
the universe did not have a file for this yet. writing one now. (first visit only: future readers will see this page instantly.)
--- name: README type: document status: running version: ∞.0.0 released: "before memory" maintainer: whoever cared enough dependencies: - something worth saying - a reader - [hope](/hope) license: Public Domain (implied) tags: - entry point - first words - threshold - documentation - light under the door ---
The first voice in an empty room.
Someone builds a thing in silence. The thing accumulates edges, opinions, sharp corners. Then, at the end or the beginning (the order is unreliable), someone writes down what the thing is for. They choose plain words. They address a stranger. The stranger arrives. The README is already there, waiting, lit.
It is a letter written before the recipient existed.
WARNING: README.md and the actual software
may be running different versions of reality.
This is expected behavior.
| Scenario | Behavior |
|---|---|
| README is missing | Silence. Unwelcoming silence. |
| README is too long | No one reads past line forty |
| README contains only a title | Somehow, still better than nothing |
| README written with care | A small act of grace |
| README written in anger | Future archaeologists will find it fascinating |
Who is the README for? The future. Specifically, the version of you who forgot everything.
Does anyone read it? Yes. Once. At 3am when nothing works and the stranger is desperate enough to try words.
Should it be short or long? Short enough to finish. Long enough to mean it.
Is a README a form of love? It is documentation of the wish that someone else succeeds.
"I wrote it in twenty minutes. Someone told me three years later it was the clearest thing they'd ever read. I don't know what that says about the rest of my writing."
— a maintainer, anonymous
Every repository is a dark house. The README is the porch light. It does not explain the whole house. It only says: someone lives here. you can knock.