Building a README that invites contributors

Have completed all previous sections and modules


Pen or pencil and paper


First impressions matter! In this day and age, where we have so many devices and things calling our attention, it is really important to make sure project visitors find what your project is all about and get a sense of why they should keep reading. This can be done in several ways, so what we would like to focus on, is in content more than form for now.

When people visit your project page for the first time, they need to understand what is your goal with this project, and how you want to achieve this goal. If they feel that this is something for them, then they should be able to find ways to collaborate, and most importantly how to contact you/your team.

Remember that when we are writing about our projects and ideas, we tend to be biased in a couple of ways. For example, we tend to forget about the days when we first started the project and knew very little about the specific words in the field (jargons), or did not know the landscape completely. Another common issue is imagining that people who might be interested in your project are going to share similar background as you, and even though it is ok for a project to have people with similar backgrounds, it also loses a lot by not having people that have different ways of thinking, or see different applications to it, or even that could connect the project with different networks.

So when writing the text that is going to be the first interaction between newcomers and your project, try to keep it in mind that there are biases on the way we write and who we write it for. A good approach to avoid them is to keep the language simple, ask people who are not familiar with the project to proof-read what you wrote (and ask them to explain what your project is about). There are also online tools to check for writing complexity (you can find them on resources in this chapter). In practical terms, writing in a simple and inclusive manner, helps you to boil down the core goal of your project, but also attract others. If they understand it, they have taken the first step towards feeling that they belong and can be part of your project’s community

  • How to describe your project and tasks in a way that other people can contribute to them
  • Explanation why this is important
  • What is a README
    • Where you can find this (repo, website, one pager)
  • What should be in a good README?

Assignment: Create a README or basic project introduction


next: Building Open Projects  

Help us improve content and suggest changes to this page.