For most software projects, especially open-source ones, the README file has a genuinely unusual property compared to almost every other file in the repository: it's read by nearly everyone who encounters the project, including people who never read a single line of the actual source code — someone evaluating whether to use a library, someone deciding whether to contribute, someone trying to remember how to run a project they set up six months ago. Despite this outsized reach, README quality is often treated as an afterthought, written quickly at the end of a project's initial setup and rarely revisited with the same care given to the code itself. Platform-specific README guidance is available in the GitHub README documentation.
What a README actually needs to answer, in order
A README that serves its actual, most common readers well tends to answer a small number of questions, roughly in the order a new reader needs them: what does this project do, in one or two sentences, before any installation instructions or technical detail; how do I get it running, with the minimum necessary steps rather than every possible configuration option; and where do I go next, whether that's fuller documentation, a way to ask questions, or how to contribute. A surprisingly common failure is leading with installation instructions before ever clearly stating what the project actually does — useful only to someone who already knows they want it, and unhelpful to the larger audience still deciding. Clear communication matters when work activity may be observed; this practical example explains how employees often recognize monitoring.
This ordering mirrors a general principle discussed in the error-messages guide elsewhere on this shelf: documentation, like an interface, should be designed around what its actual reader needs at the moment they're reading it, not around the order that happens to be most natural for the person who already knows how the project works to write it down.
The gap between what a maintainer knows and what a reader needs
A README's most common quality problem stems from a specific, hard-to-avoid bias: the person writing it already deeply understands the project, and unconsciously omits steps or context that feel too obvious to mention — a required environment variable, an assumed prior tool installation, a version constraint that's second nature to the author and invisible to someone encountering the project for the first time. This is structurally the same problem the code-review guide discussed elsewhere on this shelf identifies with self-review: the author is the worst-positioned person to judge what's unclear to someone without their accumulated context, because they can't easily un-know what they already know.
- Lead with what the project does, in plain language, before any installation or configuration detail — most readers are still deciding whether they need this at all.
- Test the actual setup instructions on a genuinely clean environment periodically — an author's own machine accumulates invisible, unmentioned prerequisites over time that a fresh environment doesn't have.
- Keep the README itself short and link out to fuller documentation for depth — a README trying to be a complete manual tends to bury the small set of things its actual, most common readers need first.
- Revisit the README when the project's setup process changes, not just when someone happens to notice it's out of date — stale setup instructions are a common and easily preventable source of a bad first impression.
Why this connects to onboarding more broadly
A README functions, in effect, as a project's onboarding document for anyone encountering it — a specific instance of the more general onboarding challenge discussed in the new-developer-onboarding guide elsewhere on this shelf, compressed into a single file that has to do a disproportionate amount of a project's explaining with very little of most teams' deliberate attention. Treating README quality with the same intentionality given to a new hire's first week tends to produce a noticeably better result than treating it as boilerplate to fill in quickly once, near the end of a project's setup.
A small, periodic investment — walking through the setup instructions fresh, checking whether the opening sentence would make sense to someone with zero context — tends to pay off disproportionately relative to its cost, precisely because of how many different kinds of readers a README actually reaches.