A great README file helps your project to stand out from the sea of open-source software on GitHub. In this article, I go over the key elements every README for an open-source project should contain. It also includes a README.md template for use in your own projects.

In my books, every README should cover at least the following:

1. What your project does
2. How to install it
3. Example usage
4. Changelog
5. License and author info

1. What your project does

Potential users of your project should be able to figure out quickly what the purpose of the project is. Make sure to get this information across early on! A good way to do this right is by providing:

• a concise, single-paragraph blurb describing your project; and

• a representative screenshot (or even better, an animated GIF) that shows your project in action.

2. How to install it

If people like your project they’ll want to learn how they can use it. Although it may seem straightforward to you how to install your library or tool, it will trip people over and frustrate them if you don’t provide installation instructions.

It sends potential users running if there are no instructions at all or if they are overly complicated. Make this step as simple as possible. A good way to provide install instructions is by:

• having a code block in your README that shows exactly what folks need to type into their shell to install your software; and

• doing this for all platforms that your software supports if there’s a difference between them (e.g. OS X/Linux/Windows).

3. Example usage

Besides, install instructions having a good usage section is essential, too. Otherwise, how are people going to figure out how they can get to the good stuff after they’ve made it through the install process?

I like doing this by putting up another code block with a few useful and motivating examples. Again you’d lay out exactly what people need to type into their shell or click in the UI to get the examples working.

4. Change log

Users of your project want to know what changes were made compared to the last version. I know that GitHub has the “Releases” tool for this but I still like having a condensed change log in the README.

Another positive side effect of putting the change log into the README is that it becomes easy to also share the change log on package repositories like npm, or PyPI.

I usually just make a bullet list with a bullet for each release and the key changes made in that release.

What I like about this approach is that you can give credit to other contributors publicly. The README is likely the first thing that new users see and it’s nice to give contributors on the project a shoutout there. They helped make your project more awesome, so share credit where credit is due.

5. License and author info

Providing licensing and contact information is important to clarify the legal status of your project. GitHub recommends that you include a LICENSE.txt in your repository’s root directory. Although this convention exists, it’s a good idea to include a brief section in the README with:

contact information for the author and
a quick statement about the license the software is under. I usually do this by saying “XYZ is available under the MIT, GNU license. See LICENSE.txt for more information”. If you’re extra nice you can put a link to the license file.