18 elements that shouldn't miss in your open source README

When people see your repository, they might not directly understand the purpose of your project. That's what your README is for. It explains what your project is about, navigates developers through it, and gives an overall impression of what developers can expect when they contribute to your project. It is the landing page of your project and therefore you should take your time to create it.

A good README should contain all the necessary information, be compact, well structured and up-to-date. Now that we have explained why it is important to have a README, we will show you how you can build a great one yourself by including these 18 elements:  

‍

TL;DR Checklist:

1. Self-explaining Name
2. Table of Content
3. Short and to the point Description
4. Community Support
5. License
6. Step-by-Step Documentation
7. Installation Guide
8. Custom Badges 
9. Necessary Requirements
10. Examples of Usage 
11. Contribution Guidelines
12. Code of Conduct 
13. Authors and General Acknowledgements
14. Appealing Visuals
15. Transparent Roadmap 
16. Up to date Project Status 
17. Project Motivation 
18. Used Technologies

1. Name‍

If you think about what makes a great headline for a news article, then you immediately think of a catchy, short name that increases your interest in reading it. Of course, a README is not the same as a news article, but still incorporating these criteria increases the likelihood of people reading it. Additionally, it should contain the name of the project and be self-explanatory in the sense that you get a solid idea of what the project is about.‍

2. Table of Contents

Especially if your README is rather long, you want to include a table of content. It organizes and structures the README and gives users easy access to the necessary information. It can work as a simple list and is linked to the headings. GitHub automatically creates tables of contents for your README files, you don’t have to insert any special markdown. 

3. Description

Grab your reader's attention. Your description is the most important part of your README, therefore invest time in creating it. Explain what your project specifically does, which technology you used and why, describe what challenges you faced or think that you will face in the future. Provide a high-quality summary of what makes your project valuable to the user and what the benefits of using it are. 

Your description should aim to answer the following questions: 

• What is the purpose of your project? 
• Why should someone contribute to it?
• How does it work? 
• Who is it for?

In order to answer these questions, you can divide your description into subsections. Keep in mind that the other users don’t know what your project is about, therefore explain everything as simple, short and understandable as you can. 

4. Support 

If your community is looking for support, tell them where they can find it by providing a support plan. This is extremely useful to current users. It can be any combination of an issue tracker, a chat room, an email address, etc. You can also include a detailed guide about the support: usage, functionality, fixing format problems etc.

5. License 

If you own an open source project you should decide which license you would like to use. This section lets other developers know what they can and cannot do with your project. 

Creative work, which includes code, is by default under copyright. If you don’t include any information about licensing, users expose themselves to a high risk for litigation when they work, modify, copy or distribute your project. This doesn’t apply to platforms such as GitHub, where you have to accept their terms and conditions, which allows users to view and fork your code, but might not include using or sharing it.

An open source license allows you to keep the copyrights to your code and still allows other devs to work with it. So, in conclusion, be sure what you want from other contributors and add the right license. You don't have to create your own license, in fact, it is best if you choose a standard license, which saves a lot of time and prevents potential legal issues. MIT and GPL are the two most used licenses in this context. 

6. Documentation ‍

Although it is boring and time-consuming, you must document every step of your process. If you want developers to participate in your project you need to provide sufficient documentation so that users can comprehend your code and understand where you started and how you grew to where you are now. This will make it as easy as possible for devs to get involved and contribute to your project. One way to ensure detailed documentation is to create a wiki and link it in your README.‍

7. Installation ‍

Real simple -  the Installation section, should describe how to install the module, for example using Yarn, NuGet or Hembrew. Make it as comprehensible as possible, so even novices, who need a bit more assistance are able to understand and follow your README. Giving details to developers will increase trust and the number of people using it.  Additionally, you can include GIFs to clearly visualize how to install your project. ‍

8. Badges

‍Badges, although not necessary, can be extremely useful and improve the overall quality of your README. They convey metadata, for example, if tests are passing for the projects. Clicking on the badge will lead you to the associated site for more information. In general, they come in different colours: 

• Green for passing
• Red for failing
• Yellow for unknown states 

If you are looking for some inspiration or want to create your own badges you can go to shields.io. 

9. Requirements‍

Including the necessary requirements to explain to developers how to use your code is especially useful to new users. Don’t forget to include the following aspects:

• Language
• Language version 
• Package managers
• Operation systems 
• Add links  
  

It can also be of advantage to add a requirement subsection when your project only runs in a specific context.

10. Usage

You can use examples in order to demonstrate how to use your application. Therefore you can add specific instructions, for example how to run your application after installing and configuring it. Typically, many projects include a “Hello World” example in their README.

11. Contributing

Do you want users to contribute to our project? Yes? There are two different approaches that you can take when you want people to contribute to your project. You can tell them how they can contribute as a community member or as a developer. 

Community Member: 

You can ask your community members to e.g.:

• Talk about your project on different social media platforms or write blog posts or articles about it
• Answer issue tracker to help other community members
• Financially support by for example subscribing to a paid account
  

Developer: 

State what developers requirements should be and what kind of assistance you are looking for. Give detailed and explicit information on how to get started on your project, how they can contribute, what kind of assistance you are looking for:

• Add Contribution Guidelines 
• Include issue labels and explain what they mean
• Describe additional setup steps 
• Add information about the development and review process
• Explain Coding standards 
• Set up a Code of conduct 
  

You can also do this by including a CONTRIBUTING file, which is a collection of your guidelines put in a separate file. This section can make a difference if it comes to if people will stay users or become contributors.

12. Code of Conduct

If you have a code of conduct you can clearly communicate the values, principles, and dos & don'ts of your community. It is a living document that can be added, refined and changed the entire time. Give detailed information on what kind of behaviour you do not want in your community and what the consequences are if people don’t respect that. You should also implement a section that gives information on how people can report unwanted behaviour and provide contact, such as an e-mail address, where users can reach out to. 

13. Authors and acknowledgement 

Praise your community and your maintainers for their contribution to your product. You can do this by providing information about:

• Website links
• GitHub profiles
• Twitter profiles
• Contact information 
  

If you want to thank someone explicitly for using their code, helping you with a difficult problem or because they inspired you to build the project in the first place, you can provide a shoutout link in your README. Give Credit to whom credit belongs, after all, we are all in this together.

14. Visuals

Humans are visual beings, therefore animations or pictures tend to capture our attention more than just plain text passages. Depending on what you are making, it can be a great idea to include screenshots or even a GIF in it, since they can demonstrate in a more comprehensible way how something works, in comparison to describing it just with words. 

If you want to create your own GIFs to explain how certain features work, you can record your screen and export it as an animated GIF file. Focus on the most important aspects, since the file will be too large if the recording is too long. You can also just use screenshots to describe how something works. 

Structure your layout accordingly and make it visually attractive: use graphics, pictures, screenshots, and GIFs to show off the functionality of your project. Including a logo can help your project to be perceived as more professional.

15. Roadmap

Including a Roadmap in your README is not necessary but can be a nice way of summarising the implemented features, showing roughly how far in the development of the software is, and give users an idea of where maintainers want to take the project in the future. It can also be used as a tool for yourself so you can keep track of your project without having to use a different management tool. 

16. Project Status

Keep your community and maintainers updated about the status of your project: If you are currently not working on it just put a note there and inform developers that it is under maintenance. If you stopped working completely on it, or in the best case if you are still actively working on it, let the people know it as well. 

Someone might find your project interesting and fork it or volunteer to work as a maintainer or owner. This would allow for your project to still keep on going. Another option would be making an explicit request for maintainers, so you would still be the owner of the project. 

17. Motivation 

What motivated you to start the project? Why does your project exist? Explain to fellow developers what the motivation behind your project is, what makes it stand out from other projects and how it is maintained. 

‍18. Technologies

Explain to your community which technologies and frameworks you used to build the project and why. You can add different sections such as “Features” and “Technology Stack”. Listing the features can make you stand out from other projects, who are similar to yours. The technology stack section explains which technologies you are using in your project and why.

Final Words

Those are the main elements that you should include in your README. If you are looking for some inspirations or guidance for a well put together README you can take a closer look here, where we gathered some great examples for you: 

• Closures
• Tensorflow
• Flutter
• Monica Hq