Building Software Together

Chapter 21: How to Welcome Newcomers

To survive and thrive, a community must attract and retain new members and help them be productive. These rules, taken from [Sholler2019], describe how to do this.

Communities of practice

What exactly do we mean by "community"? In the case of open source and open science, the most usual meaning is a community of practice [Lave1991, Wenger1999] with three characteristics:

  1. Participants have a common product or purpose that they work on or toward.

  2. They are mutually engaged, i.e., they assist and mentor each another.

  3. They develop shared resources and domain knowledge.

Be welcoming.
Projects should not just say that they welcome new members: they should make an effort to foster positive feelings by posting a welcome message on the project's social media, offering assistance in making an initial contribution, and connecting them with existing project members.
Help potential contributors evaluate if the project is a good fit.
The first and most important step in being welcoming is to help them determine whether this project is a good fit for their interests and abilities. To do this, the project should explicitly state what the different types of skills required are. This information should be easily accessible and guide new members to the tasks they may handle.
Make governance explicit.
[Raymond2001] described an egalitarian world in which everyone could contribute equally to open projects. Two decades later, we can see how misleading it was, and how unequal and unwelcoming projects can be if authority lies with those willing to shout loudest and longest [Cohen2018]. Large, well-established projects that incorporate as non-profits are required to promulgate bylaws; smaller projects should have some explicit governance that explains who gets a say in what and how to become someone whose vote counts (Chapter 2).
Keep knowledge up to date and findable.
A single project may use wikis, files in GitHub, shared Google Docs, old tweets or chat messages, and email archives; keeping information about a specific topic in a single place and clearly defining the purpose of each communication medium saves newcomers from having to navigate multiple unfamiliar data sources to find what they need [Lin2020]. At the same time, outdated documentation may lead newcomers to understand the project incorrectly, which is also demotivating. While it's hard to keep material up to date, community members should at least remove or clearly mark outdated information.
Have and enforce a Code of Conduct.
We discussed this rule in Chapter 3, but it bears repeating here. Your project's culture is defined by the worst behavior it tolerates [Gruenert2015], and every instance of bad behavior will drive current and potential contributors away.
Develop forms of legitimate peripheral participation.
Newcomers become members of a community by participating in simple, low-risk tasks that existing community members believe are valuable. Through this legitimate peripheral participation, newcomers become acquainted with the community's tasks, vocabulary, and governance so that they can ease into the project. For example, submitting pull requests on GitHub can be daunting for newcomers; asking people to file issues about bugs they have found requires less up-front work, but is accepted as also being useful.
Make it easy for newcomers to get started.
One way to facilitate legitimate peripheral participation is to make it easy for newcomers to get set up so that they can start work on contributions. Getting set up to work on a project—going from "I want to help" to "I'm able to help" to "I'm helping"—is often someone's first experience as a community participant. Any complexity or confusion at this point is therefore a significant barrier to participation [Steinmacher2014]. By treating the process of getting involved with the same care and attention you give to the product itself, you're making it clear that you value those contributors' time and effort
Use opportunities for in-person interaction—with care.
Combining newcomer-friendly events and activities with larger gatherings such as conferences amortize participants' financial costs and travel time. However, potential contributors might shy away from the project if they are introverted, suffer from social anxiety, or have had bad experiences in the past in face-to-face settings. A Code of Conduct helps allay these concerns, but some newcomers may still feel uncomfortable in group settings. In this case, not going to a meetup may leave them feeling less a part of the community.
Acknowledge all contributions.
People in open source sometimes joke that a programmer is someone who will do something for a laptop sticker that they would not do for a hundred dollars. The kernel of truth in this joke is that gratitude and recognition are the most powerful tools community builders have. It is therefore crucial to acknowledge newcomers' contributions and thank them for their work. Every project should therefore adopt and publicize guidelines describing what constitutes a contribution, how contributions will be acknowledged, and how they will be used.
Follow up on both success and failure.
Once someone has carried their first contribution over the line, you and they are likely to have a better sense of what they have to offer and how the project can help them. Helping newcomers find the next problem they might want to work on or pointing them at the next thing they might enjoy reading is both helpful and supportive. In particular, encouraging them to help the next wave of newcomers is both a good way to recognize what they have learned, and an effective way to pass it on.