How to write a README: where every good product starts
How to write a README that works as your first design document: it forces you to answer who the project is for and how it runs, in fewer than five commands.
Try writing the README before you write the first line of code. You'll be surprised how many design questions come up in just ten minutes.
What does a minimal README need?
- One sentence on what problem the project solves.
- How to install and run it, in fewer than five commands.
- How to run the tests.
- Where to ask when something goes wrong.
git clone https://github.com/your-name/your-project.git
cd your-project
npm install
npm run devA README is a test of simplicity
If setup needs two pages of explanation, the problem isn't the documentation, it's the process itself. A good README usually brings good automation scripts along with it.
Test it on a newcomer
The cheapest test: ask someone who has never seen the project to follow the README. Every time they have to ask you something, that's one line to fix.