How to write a README

The README is the first thing almost anyone sees and perhaps one of the critical parts of the project. It serves as an advertisement for the product, indicator of for what users it can be relevant, the primary user’s guide and the way to get new collaborators up to speed.

When writing the README keep your users in mind, they include:

This guide goes into the primary elements any README should have, the bare minimum: what the project is; how to install, run and deploy; how to develop and test; and how to contribute.

1. The project name and description

The README is an introduction. It should assume the reader knows absolutely nothing about the software and should provide a brief introduction. If software were a screenplay, the README would be the elevator pitch. If a person finishes reading the first 10 lines of frobnicator/README and still does not know if frobnicator is a widget library, accounting software, or a video game, then the author of the README has failed. — William Pursell on StackOverflow

Give your project a short name by which people can refer to it. Preferably the repository name is similar. Descriptive names are great. However, feel free to get creative.

The description is a high-level overview of what the project is for, what it does and in what way it should be used. The description can double as a mission to keep you focussed and on track, so it is wise to define this as early in the process as possible.

Be sure to answer these questions in your description:

Start with the most important things so people can continue their search if this project is not what they are looking for.

Make this section shine: If your project has a front-end include a screenshot here; if there is a demo or there are live examples, include links; if there are features, list them.

2. How to install, configure, run and deploy

The basics a user needs to know to use the project. Be sure to document every necessary step and some common edge cases to get started and point to relevant further documentation if available.

These sections can be quite technical. You don’t need to explain everything as and you can expect users to search the web for what they don’t understand.

We find it works really well if you follow a two-step approach to develop the content for this section: first, help someone setup the site who has never done it before, and then write down the exact instructions. Next, ask someone to follow those instructions and see if you’ve missed anything. — 18F: Making READMEs Readable

Make sure that these sections are always up-to-date. If you change functionality in the code, update the README concurrently.

Tip: If this section gets long and tedious it might be worth it to try and simplify the process of getting started, as ease of use is one of the key reasons for developers to use a project.

3. How to develop and test

Everything a developer needs to know to work on this project, including style guides, how tests work and how to use the development tools.

4. How to contribute and ask questions

Here you can describe how to get involved in the project, contribute and ask questions.

If you have a CONTRIBUTING file, be sure to point to it from your README.

Other things to include

Add more information if you think it is necessary as long as the README stays a document that is readable by every new user. For instance, if your install guide becomes very long consider creating a separate guide for this in the form of an INSTALL file or a guide in your documentation.

Depending on your project you might also need to explain more about:

Inspirations and further reading

All Guides

Contributing

How to contribute to our Open Source projects

Docker

Hoe kunnen de Docker images van onze projecten worden gebruikt

How to write a README

The goto file to see what a project is and how to use it