Project README
The README skeleton that answers a newcomer's four questions in order: what is this, how do I run it, how do I use it, how do I change it.
Last updated
Fill in the blanks
Assembled in your browser — nothing you type is stored or sent anywhere.
Your document
How to use it well
- →The one-liner earns the reader's next 30 seconds — write it for someone deciding whether this repo is even relevant to them.
- →Getting-started commands must be copy-paste runnable on a clean machine; every assumption you skip becomes someone's first issue.
- →Cut any section you'd fill with boilerplate — an honest short README beats a template fully populated with nothing.
Part by part
- {{one_liner}}
- One sentence on what this is, immediately under the title. It is the only part many visitors read, and its absence is the most common README failure.
- ## Getting started
- Before usage, because a reader who cannot install it will not reach the examples. Ordering here follows what a newcomer does, not what the author finds interesting.
- ## Project structure
- Orients a contributor before they open the directory. It is what turns a repository from a pile of files into something navigable.
- one concern per PR
- States the contribution expectation up front, which is cheaper than saying it in review on someone's first attempt.
Common mistakes
A README that opens with badges and a logo.The first screen is the most valuable space in the repository, and decoration occupies it. What the project does should be visible without scrolling.
Install instructions that assume the environment.A command that works because you already have the runtime, the credentials or the config fails for everyone else. The instructions should start from a clean machine.
No usage example.Description tells a reader what a project claims to do; an example shows it. Most people decide whether to use something from the first code block, not from the prose.
Questions
What actually belongs at the top?
The name, one sentence on what it is, and the fastest path to seeing it work. Everything else — badges, contributor guides, philosophy — can go below the point where someone is already interested.
How much detail in getting started?
Enough for a clean machine, including prerequisites and their versions. The most common failure is instructions that work only for someone with the author's setup already in place.
Should the README document the whole API?
No — link to it. A README that becomes reference documentation stops being an introduction, and both jobs are done worse than either would be separately.
How do I keep it current?
Test the install steps periodically, ideally in CI on a clean image. A README rots silently, and the failure is invisible to everyone who already has the project working.