The README is the first file a person opens when they come across a project: a code repository, a script shared with colleagues, a folder of automations left to whoever comes next. In a few seconds it has to answer three questions: what is it, do I need it, how do I make it work.
A badly written README does no visible damage straight away. The damage comes later: repeated requests for help, broken installations, a project abandoned because nobody, not even the author six months on, remembers how to start it.
The thirty-second rule
Whoever opens the README reads the beginning and decides whether to continue. The first lines must therefore contain:
- the name of the project;
- one sentence saying what it does, in concrete terms;
- who it is for or in what situation it is useful.
An example:
# rename-scans
Bulk-renames the PDFs produced by the office scanner using
the date and reference number read from the first page.
Designed for people who archive dozens of scanned documents a day.
Compare it with a typical opening such as «This project is a powerful and flexible document management tool»: it says nothing you can verify.
The essential sections
Not every project needs everything, but this structure covers most cases:
- Description: what it does, possibly a screenshot or an example of the output.
- Requirements: operating system, versions of the languages or programs needed.
- Installation: the exact commands, in the order they must be run.
- Usage: the most common example, ready to copy and paste.
- Configuration: options, environment variables, settings files.
- Known issues and solutions: the errors people run into most often.
- How to contribute or report problems, if the project is shared.
- Licence, if the code is distributed.
Installation: commands, not stories
The installation section is the one read most carefully and got wrong most often. A few rules:
- Complete commands in code blocks, ready to copy. No «install the dependencies» without saying how.
- One command per line, in the right order.
- Say where to run the command: «from the project folder», «as administrator».
- Show how to check that the installation succeeded.
git clone <repository-address>
cd rename-scans
python -m venv .venv
source .venv/bin/activate # on Windows: .venv\Scripts\activate
pip install -r requirements.txt
python rename.py --version # should print the version number
Usage: example first, then options
People learn from examples. Put the most frequent case first, with an input and the expected result:
python rename.py ~/Scans/today
# 2026-10-14_ref-0457.pdf
# 2026-10-14_ref-0458.pdf
Only then the full list of options. For long lists a table is more readable:
| Option | Effect | Default |
|---|---|---|
--dry-run |
Shows the new names without renaming | off |
--format |
File name pattern | {date}_ref-{number} |
--recursive |
Also processes subfolders | off |
Configuration and secrets
If the project needs access keys, passwords or server addresses, the README must explain where to put them without ever containing them. The cleanest way is to provide an example file, such as config.example.yaml or .env.example, with dummy values, and tell people to copy it under the real name, which is excluded from version control.
Known issues
This section grows out of the questions you receive. Every time someone asks for help with the same problem, the answer goes into the README:
- Symptom: the exact error message, so it can be found by searching.
- Cause: one sentence.
- Solution: the command or setting to change.
Writing style
- Short sentences, imperative mood in instructions: «Run», «Copy», «Open».
- No unexplained jargon; if a term is necessary, a one-line definition.
- Consistent
##headings, so platforms generate a navigable table of contents. - Update it together with the code: a README describing an old version is worse than a short one.
In my work, before I consider a tool finished, I try to install it on a clean machine following only the README. Every step where I have to «remember» something is a missing line.
In short
- The first lines state the name, the concrete function and the intended audience.
- Installation with complete commands, in order, with a way to check the result.
- In usage, the most common example comes first, then the list of options.
- Secrets never go in the README: provide an example configuration file.
- Recurring problems become a section, and the README is updated along with the code.
