Xiaoya Xia fell in love with open source at the China Open Source Conference in 2019.

Xia was a computer science student at the East China Normal University in Shanghai, where the conference was held. She was already interested in open source, but the conference was a turning point in her academic career. “The atmosphere was great and I realized how much fun open source is,” she says. “I got to meet people in the community and learn about their projects. It was an eye-opening experience.”

In the fall of 2020, she decided to get directly involved with open source by participating in Google Season of Docs, a program that helps match technical writers to open source projects that need help with documentation. She ended up working with CHAOSS, an umbrella organization that maintains tools for gathering and analyzing data about open source projects.

Working with a 1:1 mentor at CHAOSS, she was soon documenting the community's diversity, equity, and inclusion(DEI) requirements for the CHAOSS Badging project. "There's a lot of talk about DEI in open source," says Georg Link, the co-founder of CHAOSS. "We wanted to create a set of actionable steps that event organizers can take to demonstrate that they've really thought through DEI requirements." Once an event organizer has met the requirements, they can apply for badges reflecting how well they perform on certain DEI metrics, such as speaker demographics, attendee demographics, and code of conduct. 

Now, over a year later, Xia is still involved with CHAOSS, organizing community events in China.

Xia is exactly the sort of contributor open source projects need. Maintainers often struggle to attract enough people to work on non-code aspects of a project, such as documentation, community management, and support. “Documentation is the biggest place where we'd like more contributors,” says Mike Bayer, maintainer of SQLAlchemy. “It can be overwhelming trying to juggle code contributions from brand new developers who aren't familiar with a project. We wish we had more people who wanted to start out with non-code contributions.”

Contributing to open source has become an important part of any software developers’ career and how to get started with open source is a frequently asked question among beginner coders and veteran engineers alike. 

But an equally important question is what can open source project maintainers do to onboard new talent like Xia, who can pitch in to help with non-code contributions? Here are some tips from the CHAOSS community.

Secret 1: The personal touch

While the CHAOSS projects don't do a lot of active recruiting, they do participate in programs like the Open Source Promotion Plan and Google's Summer of Code and Season of Docs programs. “These students are always good to work with,” Link says. “But we screen the candidates and have them demonstrate that they have the skills to complete their projects.” That diligence pays off. “All our students have completed their projects, which is really amazing,” he says.

The real secret sauce, however, isn't screening contributors. It's mentorship. “Having a dedicated person who engages with new community members helps them overcome hurdles and stay involved with the project,” Link says.

The 2021 State of the Octoverse report found that mentorship increased productivity in open source projects by 46% percent and tripled the chances of having a healthy culture.

Of course, it’s challenging to devote that sort of time. “It's a paradoxical constraint,” says Sean Goggins, another co-founder of CHAOSS and maintainer of Augur. “Fostering a strong community takes pressure off maintainers so that they can focus more on the technical side because there are other people to take care of non-technical things. But community management takes time away from the technical side of the maintainer role.”

But it's worth it. Ana Jimenez Santamaria—a program manager at the Todo GroupTodo, which helps organizations start their own open source programs—got her start in open source by doing graphic design work for the CHAOSS project GrimoireLab. She worked for Bitergia, a company founded by GrimoireLab's creators to provide commercial support for the project, and was encouraged to work on open source as part of her job. Her first contribution was simple: she uploaded some missing images to the GrimoireLab platform. She says that without the mentorship from the open source maintainers, she would have struggled to apply her design skills to the project. 

Understanding the process of contributing to open source is a common struggle. “When I first began contributing to open source, the hardest part of getting started was trying to understand how I could make Git do what I needed it to,” Rose Judge, an open source engineer at VMware, wrote in a forthcoming guide for The ReadME Project. “I still remember being asked to update one of my first PRs and despite my best efforts searching all corners of the internet, I couldn’t figure out how to do it, so I ended up closing the pull request, re-cloning my fork, and opening an entirely new pull request.”

Secret 2: Awareness

Non-code contributions can be a gateway towards contributing code. But it's important for maintainers not to try to stick newcomers with all the work no one else wants to do. One key aspect of mentoring is ensuring that contributors have a chance to work on what they want to work on. 

“The work needs to be done, but oftentimes it’s under-prioritized or there aren’t people who volunteer to do it,” writes Keeley Hammond, who started out in open source by organizing events and writing documentation before contributing code to Electron. “The people that do volunteer often come from marginalized backgrounds. People can take this work for granted, even though it requires a very real skill set. So if you’re a marginalized person doing work that is important but under-valued—even if others recognize that it’s valued incorrectly!—you risk getting trapped in a self-perpetuating cycle.”

Many people prefer to work on non-code tasks, or find that they prefer it, but maintainers need to ensure that work is spread evenly.

Secret 3: Documentation

Besides devoting time to mentoring individuals, maintainers can take other steps to help onboard new contributors, such as tagging “Good First Issues” in GitHub. The more “Good First Issues” the better. According to GitHub's The 2021 State of the Octoverse report, projects with about 25% of their Issues marked with the tag saw 13% more contributors, as opposed to those without. Those with 40% of Issues tagged as “Good First Issues” saw 21% more new contributors than those without.

Documentation is one of the most helpful ways to onboard new contributors. “GrimoireLab's documentation helped me understand the software,” says Venu Vardhan Reddy Tekula, a Google Summer of Code volunteer who is now a part-time community manager for GrimoireLab. “I wouldn't have been able to get started without it.”

Augur recently overhauled their documentation in the last six months and it’s clearly made a difference. First, they added a section to the beginning of the documentation that outlines common problems people have installing the software the first time. They also created a quick-start guide to Augur setup and a set of install scripts that reduce the number of steps required to get started.

Contribution guidelines are one of the most important types of documentation every project should have: the Octoverse 2021 report found that repositories that include contribution guidelines are 17% more productive.

While writing documentation does also take time away from maintainers who want to focus on code, it’s an investment for the future. Once a project develops momentum, that early investment can pay for itself.

“As I worked through the documentation, I fixed typos along the way,” Tekula says. “That was my first contribution.” From there he went on to fix even more. Now he helps mentor other contributors who want to work on documentation and other aspects of the software.

In other words, documentation and mentorship can create a positive feedback loop that sustains projects and builds community. Committing to these areas will make it easier for new people to get involved in open source and, ultimately, make open source better for everyone.