Amey-Thakur README writing
The README is the project's front door, and most readers decide in the first screen whether to continue. Lead with what it is and why they should care, get them to a working state fast, and put reference material where it belongs: below, or elsewhere.
Method
- Answer what/why/for-whom in the first screen. One or two sentences: what this is, the problem it solves, who it is for. A reader landing cold should know in ten seconds whether to keep reading (see landing-page-strategy's five-second test: the README is a landing page for a different audience). Badges and a tagline, not a wall of prose.
- Quickstart before reference. The fastest path to a working result: install, minimal example, expected output (see tutorial-writing's tested-steps rule). A reader wants to see it work before they read the API; front-loading configuration options and architecture buries the moment that earns their investment (see user-activation's time-to-value, docs edition).
- Show, then tell. A concrete runnable example (copy-pasteable, actually tested: see docs-as-code) teaches more than paragraphs of description; lead each capability with what it looks like in use. Abstract feature lists convince nobody; a working snippet does.
- Structure for scanning. Clear headings in a predictable order (what, install, quickstart, usage, configuration, contributing, license), short paragraphs, a table of contents for long ones. Readers scan for their question; a README that must be read linearly to find anything fails the impatient reader, which is all of them (see docs-information-architecture).
- Link out for depth, keep the README lean. Detailed API reference (see api-reference-docs), architecture (see architecture-diagrams), and guides live in linked docs; the README orients and launches, it does not contain everything. A README that tries to be the whole manual becomes the manual nobody reads.
- Include the operational essentials. How to contribute (see onboarding-docs), where to get help, license, and status (maintained? version?): the metadata that tells a reader whether to depend on this. Then keep it current: a README describing an old install command is the first thing that breaks trust (see docs-maintenance).
Boundaries
- The README's job is orientation and quickstart, not comprehensive reference; resist the pressure to document every option there (that is api-reference-docs' job, linked).
- Audience shapes everything: a library README (developers integrating) differs from an application README (users running it) differs from an internal-tool README (the team maintaining it); write for the actual reader.
- A great README over an undocumented codebase is a promise the rest cannot keep; it is the entry point to a documentation system (see docs-information-architecture), not a substitute for one.