Every open source project contains a README .md text file to introduce and explain a project. Because the README is the first item a user sees, it should communicate the most valuable information related to your project, clearly and succinctly. It’s like a landing page for your repo, where you get the opportunity to welcome new users or contributors while directing them where to go and how to get started. Ovio displays the README as the most visible element on a project’s page, so you can ensure that external contributors can understand your project’s goals, code, and structure immediately.
Let’s take a closer look at some best practices for creating a readable README, so you can introduce your project effectively, attract more contributors, and make a solid first impression of your project.
Explain what the project does and why it exists 📣
The first few lines of your README are essential to capturing the attention of potential contributors. Start by including a brief introduction stating the purpose of your project. You’ll want to include a description of your motivations behind its development and maintenance. By clearly introducing your project, rather than only showing your project’s code, you can give contributor’s a sense of who’s behind the project and why it matters, while also attracting good talent. Think about the beginning of your README like your project’s mission statement, introducing users to its value.
How to download and install the code 📥
We recommend offering quickstart instructions in your README on how to download and use your code. Offering step-by-step guidance with examples and explanations is a great way to get users comfortable with your project before they have time to feel intimidated or hesitant about getting the development event running.
How users can get started with the project 🏁
You want your README file to encourage contributions, so users feel inclined to get started. While more detailed instructions on how to get started on the project should be included in the contributing.md file, the README is a great place to welcome and list possible contributions, tech or non tech related. Read more about the contributing.md file in our article How to attract open source talent to your community.
How to test the code 🧪
Showing users how to run tests with your code is important to ensuring your project’s reliability and success, as well as a user’s contribution experience. We recommend walking through an example of how to test the code, describing the process in a step-by-step manner and offering visuals or screenshots along the way. Additionally, as your project evolves and changes over time, your documentation will require updates. Make sure your README’s instructions on how to test the code stay up to date, so when a new developer on-boards your project they can easily get to work.
Where users can get help with your project 🆘
If a contributor needs help using your code, it should be readily apparent who they can reach out to. Specify in your README file if a user should contact a certain email address for requests and feedback, or guide them to a discussion board in Github or Slack where they can create issues or communicate with other users working on the project. Basically, you want to help your contributors help you, so provide them with clear instructions and necessary contact information.
Share your license 🔒
You’ll also want to include some information about the project’s license in your README. For example, you can write a short note to your contributors saying “This project is licensed under the terms of the Apache license.” We recommend including more detailed information on your project’s license in a separate text file in the root of your repository.
Some projects include information about their license in their README. For example, a project's README may include a note saying "This project is licensed under the terms of the MIT license."
As a best practice, we encourage you to include the license file with your project.
Don’t forget to include lots of graphics 🎨
Remember people respond well to visuals, so adding a graphic at the top of your README that communicates your repo’s purpose can help attract a contributor’s attention. By including visuals throughout, such as drawings, screenshots, or diagrams, you have a better chance of keeping someone’s attention who is likely skimming your README.
It’s important to give thanks and recognize those who support your project. The README is a great place to express your gratitude and recognize different contributors. We recommend including the names of top contributors, along with the icon image of your project and its latest release note.
Resources:
Template
Awesome README
