How to Write a README That People Actually Read

Open GitHub on any given day and you'll find repositories with a single line README ('a fast JSON formatter') and no installation instructions. You'll also find 50-page READMEs that bury the installation command under 2,000 words of motivation. Neither is useful. Here's the structure that actually works.

The One-Sentence Description

First line of the README: what it does in one sentence. Not 'FastJSON is a modern, blazingly fast JSON formatter built for developers who need performance and reliability.' Just 'Format and validate JSON in under 1ms. Works in Node.js and the browser.' Specificity beats marketing language every time.

The Section Order That Works

1. 1One-line description + key benefit
2. 2Installation (exact commands, copy-paste ready)
3. 3Quick start example (the smallest working example)
4. 4Common use cases with code
5. 5Configuration reference
6. 6API reference (or link to it)
7. 7Contributing guidelines
8. 8License

The Installation Section

Never say 'install the package using your preferred package manager.' Say 'npm install fast-json — or yarn add fast-json if you use Yarn.' Assume nothing and be complete. Include the import statement immediately after installation so the reader's first code works without hunting for it.

Code Examples: The Critical Section

Every example should run without modification. No placeholder values that require substitution unless you clearly mark them. No 'see documentation for details' when the detail is a parameter type. The reader's first experience with your project is running the quick start example — if it fails because of missing information, you've lost them.

Markdown Format Choices

Use fenced code blocks with language identifiers (```javascript instead of just ```) — GitHub applies syntax highlighting and makes copy buttons appear. Use a table for configuration options rather than a bullet list — much more scannable. Use collapsible sections (<details><summary>) for long sections that most readers can skip.