Contributors are the lifeblood of any open source project. A project not continually welcoming new participants might find itself stagnating—or, worse, falling apart.
So any open source project desiring long-term sustainability should think seriously about the ways it connects with, greets, and acclimates—in a word, how it "onboards"—new contributors. A well-designed onboarding process makes contributing to your project easier for participants, and it empowers contributors to positively impact the the work as quickly as possible.
In this chapter, we’ll discuss the importance of your community’s onboarding experience and examine some common onboarding resources and practices that may help your project become more sustainable.
In many ways, the experience of onboarding in a new open source community is much like one you might have in a new job.
For example, when you begin working in a new position (or in an entirely new organization), you’ll need to become familiar with new people, new tools, new processes, new norms, new policies, and more. And you’ll likely feel motivated to do these things quickly, because you’re eager to demonstrate your value to the organization and become comfortable in your new environment so you can do your best work. The faster you feel like you’re making an impact, the more likely you are to stick around. And the more satisfied you’ll be.
But you may also be joining a team with an extensive history—shared norms and customs, in-jokes, jargon, unspoken agreements, shared bonds, and a sense of collective identity. In short, your new team or organization will have a culture that pre-exists and pre-dates your joining it. Facets of this culture are largely intangible, but they’ll significantly affect your ability to collaborate with others. An effective onboarding experience equips you to understand this culture.
All of this remains true of onboarding experiences in open source communities. In particular, open source communities present onboarding challenges like:
- An asynchronous and remote environment
-
One of the great perks of a traditional office environment is that you are close to your co-workers and managers for face to face interactions and you can find them for quick questions. In contrast, when you join a new open source community, you will likely work with community members in different georgraphies and time zones. So unless there are good onboarding materials such as documentation, video tutorials, wiki pages, and other resources, it’s going to be more challenging to get started in open source communties even for experienced self starters.
- Imposter syndrome
-
When it’s more difficult to get real time help or feedback, people can easily get stuck with simple tools issues and feel less confident about their work. So a good onboarding experience in open source communities is crucial for newcomers not to feel discouraged in their early days in the community.
- Significant variability
-
No two open source communities are the same. Even for seasoned open source contributors, when they join a new community they will need to get familiar with new tools, new processes, and even new terminologies. Depending on the community, seemingly simple terms like contributions, community members, projects, upstream, etc. may mean something slightly different and can easily cause confusion for new community members.
As you work to make your project’s onboarding process and experience most effective, ask yourself these questions:
-
What can people contribute to the project?
-
Where do people contribute to the project?
-
How do people contribute to the project?
Answering the first question about your project’s onboarding process requires a good deal of work. Incoming contributors need to know what would be the most helpful contributions they could make. Quite a few projects have set up tagging on their source code repositories for "first-time contributors" or something similar, which is an excellent way to direct incoming contributors to solving issues and bugs while also introducing newcomers to the source material of the project.
The second question—regarding "where to contribute"—is one that projects don’t pose as often as you’d think. Project veterans might dismissively say, "what you need is on the forums" or "read the wiki if you need more detail." But in which specific repository are the material available? Under what organization? And what about other, similarly named projects? Ensure your project website features clear links to places where new contributors can make an impact on the project. These links shouldn’t be buried, either; they should be right on the home page, if possible.
Third is the question of "how to contribute." Too often, projects release their source code, even make it easily discoverable . . . and that’s it. You may have heard others refer to this approach as "throwing it over the wall," and it is not a phrase people tend to use politely. Too many projects will push their code or content into a public place, declare it open to all, and then wonder where all the contributors are. This can be because there is a real barrier to entry, in the lack of documentation and procedures for getting contributions into the project.
Next, let’s discuss discuss some resources and practices your project can use to eliminate these barriers and streamline your project’s onboarding process.
A key tool (and practice) for working successfully in an asynchronous environment is good documentation. Since contributors won’t typically have fellow community members available near them to provide impromptu guidance, it’s important to have important community norms, decisions, and processes well-documented in much more detail than they might be in a more traditionl work environment. Whether it’s a landing page, project documentation, wiki page, etc., a good set of references are crucial for new community members to get familiar with the community and get started. It’s also important to ensure that the onboarding documentations are up to date and reflect the latest snapshot of the community’s activity, so you want to make it easy for anyone to help keeping the contents up to date. An easy-to-use documentation tool definitely helps with this, but what’s more important is to cultivate a community culture that impresses on everyone the need for reliable, updated documentation.
This may sound obvious, but another key resource for onboarding is other community members. Even if people do not sit in the same office, having access to experienced community members to help people get started and answer questions can help alleviate the sense of isolation in the early days. Something simple like onboarding buddies who can jump on a welcome call may be enough for a small community that is relatively new. For larger and more established communities, people may have seen working groups focused on onboarding or even community members with formal titles such as coaches or mentors.
Once people resoures for onboarding are in place, this information (especially on who to reach out for help) needs to be posted in multiple places so that people feel welcome to contact their onboarding resources and feel encouraged to ask questions. If getting help is difficult, new comers will feel discouraged from engaging with the community and even decide that the community may not be for them afterall.
Whether it’s onboarding buddies, mentors, working groups, etc., you want to have a large enough pool of volunteers so that these volunteers don’t feel burned out with onboarding activities especially as the community grows. What is important is to have a culture within the community so that there is an expectation on everyone to help welcome new community members. Ideally, what we want to see is a lot of people volunteering to help others whether or not they have a formal title as a coach or a mentor. If you have a formal program for onboarding working group, mentors, etc., you should not set a high barrier to entry for community members to become an official onboarding resource. The most important qualification should be people’s willingness to help others versus other factors such as their tenure in the community or technical expertise in the project. The people who are helping with onboarding do not need to have all the answers. Rather, they need to help newcomers find answers quicker and not work alone.
When people join a new community, they may find following discussions on communication channels (such as mailing lists or Slack) to be overwhelming. To alleviate their confusion or stress, consider creating spaces in these channels specifically for new community members to use as they get started and acclimated. For example, dedicated channels such as "getting started" or "introductions" can be good places for people to feel safe asking newcomer questions. These channels also allow more experienced community members to assist with onboarding by helping answer newscomer questions or even simply by offering encouragement. It all goes a long way to making new community members feel welcome as they’re getting started.
Once new community members feel oriented and comfortable enough to begin contributing to an open source project, their next questions will be "Where can I contribute?"
So to help newcomers get started, you may wish to develop a list of work items that new community members in particular can tackle. Many communities label issues in their issue trackers with something like "good for first time contributors," "good first issue," or "help wanted," so newscomers can more easily identify tasks with which they can help immediately. Issues with these labels could range from documentation errors, easy bug fixes, or other simple tasks that will help new contributors experience early successes and therefore build their confidence. Having a contact person (or people) servinvg as mentors or coaches listed on these issues (in case people need help getting started) can also be helpful. Always remember: Issues that may seem simple to experienced community members might not be as simple for newcomers.
Many open source communities organize events aimed at connecting their members. Whether the events are collocated or virtual, they provide excellent opportunities for community members to collaborate synchronously—and get to know each other in the process. These events could be summits, hackathons, user confernces, etc. At these events, consider creating special programming or spaces for new community members. You might organize formal orientation sessions as a "Day 0" event if your budget allows for it, or a lunchtime session at which newcomers can meet other community members so they know who they can ask questions to later on.
Once new contributors have made their initial contributions to your project, they’ll begin looking for ways to make more significant impacts. To do this, they’ll often look for ways they can apply their specific skills and talents to the project.
Opportunities for volunteers to begin lending their unique talents to an open source project are called that project’s "contributor pathways." The greater the number of contributor pathways your project features, the more likely it is to recruit participants with the various skills required for the project’s success.
Your project will have any number of contributor pathways specific to it, but these pathways will generally fall into two basic categories: pathways with a community focus and those with a technical focus.
Community-focused pathways are opportunities for contribution that may not require specialized technical knowledge on the part of participants. These are pathways focused on helping new contributors document the project, raise awareness of and market the project, plan community meetings and events, etc.—all extraordinarily important aspects of a project’s eventual success. Examples include:
-
Documenting workflow and governance processes
-
Onboarding and mentoring new members
-
Localizing content into various languages
-
Copywriting (for website, newsletters, blogs)
-
Managing social media
-
Organizing events
Technically focused contributor pathways, on the other hand, are contributions requiring specialized knowledge of software development (often in a particular computing language). These pathways are focused on enchancing or refining the body of software a community maintains. Examples include:
-
Adding new features and documentation
-
Fixing existing bugs and triaging issues
-
Refactoring existing work to improve it
-
Performing quality assurance
-
Improving user interface and user experience
-
Release engineering
-
Creating and maintaining project roadmap
-
Code and user interface localization
When assessing your project’s contributor pathways, ask yourself: Does your project currently offer new (and existing) contributors opportunities to contribute rewardingly to (or even take ownership of) work in each of these areas? If not, one general way to begin expanding your project is by making concerted efforts to formalize, refine, document, and advertise these contributor pathways.
We call these "pathways" because they allow participants to deepen investment in the community gradually so they don’t feel overwhelemed and can acclimate themselves to the project’s processes and culture as they become more involved. Ideally, as your community matures, it will construct pathways that incrementally confer more responsibility and authority on contributors. Contributors following your project’s contributor pathway related to events, for example, probably won’t get started by taking sole responsibility for your community’s flagship annual event. But they might work with experienced community members on planning that event, taking charge of securing a venue, advertising, registration, and more.