A README is a document that introduces a project, system, or repository to someone encountering it for the first time. The name — “read me” — is a convention dating to the earliest days of software distribution: a file named README was the first thing a user should open.
The README is often the only documentation a reader sees. In open-source software, it is the project’s front door — it must orient a stranger quickly enough that they can decide whether the project is relevant to them and, if so, how to start using it.
An effective README answers five questions in order:
- What is this? — one or two sentences describing what the project does. Not how it works, not its architecture, not its history — what it does for the person using it.
- Why does it exist? — the problem it solves. This helps the reader determine relevance: if they don’t have this problem, they don’t need this project.
- How do I start? — installation or setup instructions. These are procedural documentation and should follow the same principles: numbered steps, prerequisites stated, expected results included.
- How do I use it? — a basic usage example. Not comprehensive documentation but enough to show the reader what working with the project looks like.
- Where do I learn more? — links to full documentation, contributing guidelines, license information.
The README’s challenge is compression. It must provide enough information to orient the reader without becoming the full documentation. Progressive disclosure is the structural principle: the README is the first layer, linking to deeper layers for readers who need them.
Related terms
- procedural documentation — the README’s installation section is procedural
- progressive disclosure — the README is the first layer of documentation
- audience — the README is written for newcomers, not existing users