Writing README text that people can follow
Knowing which sections to include is one skill. Writing the words inside them is another. This page focuses on style and Markdown, using a complete sample README for a small command-line tool as the running example.
Style rules that make a README usable
- Write for someone in a hurry. Short sentences, one idea each. Put the action first: “Run
tidyup --dry-runto preview changes.” - Show, then tell. A three-line example teaches faster than a paragraph. Explain only what the example does not make obvious.
- Use the reader’s words. Name the task they want done, such as “sort downloads by type”, before you name your internal concepts.
- Keep one name per thing. If you call it a “rule” in one place, do not call it a “filter” elsewhere.
- Every command must run as written. Copy it from your README into a clean terminal before you publish.
Markdown details that matter
| Need | Markdown | Note |
|---|---|---|
| Code block with highlighting | Three backticks plus a language name, such as bash | The language tag turns on syntax colours on most hosts |
| Inline command or file name | Single backticks | Stops the text being turned into a link or emphasis |
| Link to a heading | [Options](#options) | Anchors are the heading in lowercase with spaces as hyphens |
| Link to another file | [changelog](CHANGELOG.md) | Relative links keep working in forks and on other branches |
| Table | Pipes and a dashes row | Columns do not need to line up in the source |
| Collapsible detail | <details> and <summary> | Supported on major code hosts; good for long output |
Do not put a $ prompt in front of commands you expect people to copy. It gets pasted along with the command. If you want to show output, use a separate block or a comment line.
A complete sample for a CLI tool
Suppose the project is an invented command-line tool called tidyup that sorts files in a folder into subfolders by type. Its README might read:
# tidyup
Sort a messy folder into subfolders by file type, in one command.
## Install
```bash
pipx install tidyup
```
## Use it
Preview what would move, without touching anything:
```bash
tidyup ~/Downloads --dry-run
```
Then do it for real:
```bash
tidyup ~/Downloads
```
Images go to `images/`, PDFs to `documents/`, and so on.
Files tidyup does not recognise stay where they are.
## Options
| Flag | Default | What it does |
|---------------|---------|--------------------------------------|
| `--dry-run` | off | Print the plan, move nothing |
| `--rules FILE`| built-in| Use your own type-to-folder mapping |
| `--undo` | — | Move files back using the last log |
## Your own rules
Create a file such as `rules.toml`:
```toml
[folders]
"sheet-music" = ["mid", "musicxml"]
```
## Licence
MIT. See [LICENSE](LICENSE).
Why the sample works
- The first line after the title states the job in plain words and promises a single command.
- Install is one copyable line with no surrounding prose to skip.
- The first usage example is the safe one. Leading with a dry run builds trust before anything moves.
- Each flag appears exactly once, in a table with its default, so the reader does not hunt through paragraphs.
- It says what happens to unknown files. Answering the obvious “what if” prevents an issue report.
Wording to avoid
- “Simply”, “just” and “easily”. If the reader is stuck, these words make them feel worse and add nothing.
- Vague claims such as “blazing fast” or “powerful”. Show a concrete capability instead.
- Undefined acronyms. Spell a term out the first time you use it.
Questions
Should I use badges at the top?
They are optional. A wall of badges pushes the summary down; if you use them, keep a few that a user acts on, such as build status.
How long should a README be?
Long enough for the first successful run and the common tasks. Move reference detail to separate documentation pages.