What should go in a good README?

Short answer: a README should let a stranger understand what the project is, run it in a few minutes, and know where to go next. It does not need to be long, but the first screen must be useful.

A solid structure

1. Name and one-sentence description. What problem does it solve, and for whom?
2. Screenshot, GIF or short example. Show the result. For a library, show a minimal code sample.
3. Requirements. Language and runtime versions, databases, accounts or API keys needed.
4. Install and run. Copy-pasteable commands, tested from a clean machine.
5. Configuration. Environment variables with a short description of each. Provide an example file with no real secrets.
6. Usage. The two or three most common tasks.
7. Tests. How to run them.
8. Project layout (optional). A short map of the main folders.
9. Contributing and licence. Link to a contributing guide and name the licence clearly.
10. Status and limitations. Be honest about what does not work yet.

Example install block

git clone https://example.com/you/project.git
cd project
cp .env.example .env
npm install
npm run dev

Habits that help

• Test your instructions by following them literally on a fresh checkout.
• Keep deep documentation in a docs/ folder and link to it.
• Update the README in the same pull request that changes the behaviour.

Pitfalls

• Instructions that assume tools you already have installed.
• Badges and logos before the basics.
• Documenting every function; that belongs in reference docs.

Write for the version of yourself that returns in six months with no memory of the project.