--- 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: ∞ released: "prehistory" maintainer: whoever pushed last dependencies: - project - good intentions - text editor - optimism (often missing) license: public domain, spiritually tags: - documentation - first impressions - promises - portals ---
A letter from the past to the future, written by someone who thought they had time to explain everything.
A README is opened. It either answers the question "what is this?" or it raises twelve new ones. The reader forms a complete opinion of the project within 90 seconds. That opinion is usually correct.
The lifecycle is as follows:
"I spent four hours getting this to run and the README said it would take five minutes." — every user, always
readme:
tone: friendly_but_not_too_friendly
length: longer_than_needed
last_updated: "ask git blame"
screenshots: outdated
table_of_contents: present_but_misleading
emoji_usage: regional_preference
audience: assumed_not_specified
Q: How long should a README be? A: Long enough to answer the obvious questions. Short enough that someone reads it. This range does not exist.
Q: Should I write the README before or after the code? A: Before, ideally. You will not. It's fine.
Q: Who is the README for? A: Future you. You will not recognize yourself in it.
Q: Is this spec itself a README? A: It is a README about READMEs, which means it inherits all of the above bugs by reference.