Write the README First
If you cannot explain the thing in a page before building it, the design is not finished.
Placeholder article. Writing the README before the code is a design exercise disguised as documentation.
What it exposes
Setup steps that turn out to be conditional. Concepts you cannot name. Sentences that need three caveats. Each one is a design problem surfacing early, while it is still cheap.
The side effect
You end up with a README, written while the reasoning was fresh rather than reconstructed months later by someone who has forgotten why.
Replace this placeholder article with your own writing.
Leave a comment