Writing Project READMEs

A README is the first and often the only thing a person reads before deciding to run your project. Treat it as the front page of the product, not as documentation. Its job is to get the right person to a working install fast, and to make the wrong person leave without filing an issue.

This skill is opinionated toward self-hosted apps, developer tools, CLIs, services, and libraries. It is a flexible checklist, not a fixed template. Pick the sections the project actually needs and drop the rest.

When to use

• Writing a README from scratch for a project.
• Rewriting or tightening an existing README.
• Auditing a README and reporting what to fix (run the rubric at the bottom).

The first 30 seconds decide everything

Above the fold, a reader must be able to answer four questions without scrolling far: