README.md Best Practices: What the Good Ones Have in Common

The README is the most-read document in any repository — and usually the least-designed. It's written last, in a hurry, by someone who no longer remembers what it's like not to understand the project. The fixes below come from patterns shared by READMEs that consistently get praised: they're structural, not stylistic, and all of them are plain markdown.

The section order that works

Readers arrive with three questions in a fixed order: what is this, is it for me, and how do I start. A README that answers them in that order keeps people scrolling; one that opens with build instructions loses them.

# Project Name
One sentence saying what it does and who it's for.

## Why
The problem it solves — 2–3 sentences, not a manifesto.

## Install
The shortest working path. One command if possible.

## Usage
A minimal example that produces visible output.

## Documentation
Link out for everything deeper.

## Contributing / License

Everything else — architecture notes, benchmarks, FAQs — belongs in linked docs, not the README. Each section past "Usage" halves its readership.

Write the first line for search

GitHub shows your repo description and README opening in search results, and AI assistants quote them when recommending libraries. "A fast, zero-dependency JSON parser for embedded systems" beats "Welcome to my project!" in every context that matters. Front-load the nouns someone would actually search for.

Code blocks: always name the language

A fenced block with a language identifier gets syntax highlighting on GitHub; a bare one renders as flat monospace. The difference in scannability is dramatic for install commands:

```bash
npm install your-package
```

The same applies to config examples (json, yaml, toml) — highlighted keys are much easier to copy correctly. Our cheat sheet covers the full fenced-block syntax.

Badges: three, not thirteen

Build status, package version, license — those answer real questions. A wall of twelve badges reads as decoration and pushes the actual description below the fold. If a badge doesn't help a stranger decide whether to use the project, cut it.

Screenshots and GIFs earn their bytes

For anything with a visible interface, one screenshot outperforms three paragraphs. Reference images with meaningful alt text — ![Dashboard showing live query latency](docs/dashboard.png) — because alt text is what GitHub search, screen readers, and AI tools actually index.

Tables for options, prose for concepts

Configuration options, CLI flags, and supported versions belong in markdown tables where they can be scanned. Explanations of why belong in sentences. READMEs fail in both directions: options buried in paragraphs, or concepts crammed into table cells.

Preview before you push

GitHub renders GFM with its own quirks — line breaks, nested list indentation, and HTML handling differ from some editors. Drafting in a live-preview markdown editor catches rendering surprises before they're public. Paste your README in, and what you see is what GitHub ships.

A README is markdown at its highest-leverage: one file, plain text, read by every user, contributor, and increasingly every AI coding assistant that touches your repo. The hour spent structuring it properly is the best-paid hour in the project.