· 1 min read
Write the README before the build
If the first screen of a project cannot explain itself, the project is not designed yet.
A README is not documentation you add when the code is done. It is the first design artifact. Before a repository deserves a second commit, someone should be able to open it and answer three questions:
- What is this?
- Who is it for?
- How do I know it works?
Those questions sound like marketing. They are engineering. “What is this?” forces a boundary. “Who is it for?” forces you to pick a user instead of a persona cloud. “How do I know it works?” forces a check you can run, not a hope you can demo.
I ask for this on internal tool builds before writing any implementation. If we cannot write the README, we are usually about to build three tools and call them one. The README makes the extra scope visible because it does not fit in the first paragraph.
A useful README is short enough to be wrong in public. That is a feature. A wrong paragraph gets corrected. A wiki with forty pages gets abandoned, and the real description of the system moves into someone’s head, where it cannot be reviewed.
The same standard applies to an internal tool proposal, a team RFC, and a blog post. If the first screen does not earn the second, do not write the second yet.