What a README is for
A README is the first file most people read when they meet a project. It sits at the top level of a repository or folder, and its job is to get a newcomer from “what is this?” to “I have it running” with as little guessing as possible. It is a front door, not a complete manual. The detail belongs elsewhere, and the README points the way.
Imagine the reader as a capable colleague who has never seen the project and has ten minutes. Everything in the README should help that person decide whether the project is relevant, and then use it.
Start with what it is
Open with a title and a short description, in two or three sentences. Say what the project does, who it is for, and what problem it addresses. Avoid internal shorthand that outsiders will not know. If a reader cannot tell within a few lines whether the project is what they were looking for, they will leave.
It also helps to state the status honestly: whether the work is experimental, in active use, or no longer maintained. Readers can then set their expectations. Do not overstate what the project can do. A frank note about known limits builds more trust than a long list of claims.
Requirements and prerequisites
List what a reader must have before starting. Depending on the project, this might include:
- an operating system or hardware needed;
- tools or languages the project is written in and used with;
- any accounts, access rights or supporting equipment;
- knowledge you assume, such as familiarity with a command line.
Keep this list accurate and minimal. Avoid pinning details that you will not keep up to date, since a requirement that quietly changed is a classic source of stale documentation. When a specific version matters, say so and say why.
Installation or setup
Give the steps to get from nothing to a working copy. Write them as a numbered sequence, one action per step, and show exact commands in code blocks so they can be copied. Say what the reader should see when a step has worked, such as a message or a file appearing, so they can tell whether to continue. Principles of writing clear procedures apply fully here: be specific, keep the order right, and do not skip the step that “everyone knows”.
The best test is to follow your own instructions on a clean machine, or ask a colleague to do so while you watch. Gaps that are invisible to the author show up quickly when someone else tries.
Usage with an example
After setup, show the smallest useful example of using the project. A reader who sees a command and its expected output understands more than a page of description. Start with the simplest case, then point to more advanced use.
For hardware or process projects, the equivalent might be a short “first run” description: how to connect it, what to switch on, and what normal behaviour looks like. Where safety is involved, state the precautions plainly, and refer readers to the proper safety documentation and qualified people rather than relying on the README alone. Rules and requirements vary by country and industry.
Project layout
For anything beyond a few files, a short map helps. List the main folders and what each contains in one line each. This orients a reader who wants to look around or contribute, and saves them opening every directory. Keep it to the top level or two; deeper detail can live closer to the code.
How to test or verify
If the project has tests or a way to check that it works, say how to run them and what a passing result looks like. This reassures a new reader that their setup is correct and gives contributors a way to check their changes. Concepts such as unit tests and continuous integration are worth a line if your project uses them, though the README need not explain them.
Contributing and getting help
Tell readers how to take part and where to ask questions. At a minimum, give a contact point, such as an issue tracker, a mailing list or a named maintainer. If you accept contributions, describe the expected process in a sentence or two: how to propose changes, what conventions apply, and where to find fuller guidance. A pull requests workflow, for example, is common enough that a short note on branch naming or review expectations goes a long way. If you do not accept outside contributions, say so, which is kinder than silence.
Licence and ownership
State the licence if there is one, or say that the work is internal or not licensed for reuse. A reader should not have to guess whether they are allowed to use the material. For legal questions, rely on the licence text itself and, if needed, qualified advice, since a README is not a substitute for either. If the project belongs to an organisation, name it and give the owner or team responsible. Where open-source software licences matter to your work, read the licence terms themselves rather than summaries.
Style tips
- Put the most important information first and the details later.
- Use headings so readers can jump to what they need.
- Prefer short paragraphs and plain language over long explanations.
- Use lists for steps and requirements, and prose for explanation.
- Keep it short. A README that is too long will not be read, and its detail is better placed in separate documents.
- Plain language helps everyone, including readers whose first language is not yours.
Keeping it alive
A README is only useful while it is true. Update it in the same change as the thing it describes, and treat a README fix as a normal part of the work. Check it occasionally by following it from scratch. An out-of-date README may be worse than a short one, because it sends readers down paths that no longer work.
A good README is typically modest: what the project is, what you need, how to run it, how to check it, and who to ask. If a newcomer can get through those with no help, the README is doing its job.