SpunkArt
Command line and project setup

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-run to 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

NeedMarkdownNote
Code block with highlightingThree backticks plus a language name, such as bashThe language tag turns on syntax colours on most hosts
Inline command or file nameSingle backticksStops 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
TablePipes and a dashes rowColumns 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

  1. The first line after the title states the job in plain words and promises a single command.
  2. Install is one copyable line with no surrounding prose to skip.
  3. The first usage example is the safe one. Leading with a dry run builds trust before anything moves.
  4. Each flag appears exactly once, in a table with its default, so the reader does not hunt through paragraphs.
  5. 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.