Onboarding new contributors is hard. There's so much they don't know. How is someone supposed to contribute when they don't know the codebase, the project infrastructure, community norms, or the specific people who can give them advice? Add in the fact that often new contributors have significant gaps in knowledge about the project's domain and/or the language(s) the project uses, and it's no wonder many new contributors get discouraged and give up.

One common solution is to label certain issues in your issue tracker 'good first task' or 'bite sized task'. But there are some drawbacks to this approach. Sometimes what seems bite sized is actually much more complicated. This can be extremely discouraging for newcomers who may assume they're having trouble because they're incompetent, instead of the issue being mislabeled. The only way to be sure you aren't handing a newcomer a monster task labeled 'easy' is to actually work through the task, then throw out all the work you've done. Power to maintainers who are willing to do that, but it's a big ask to make of people we already ask so much of.

Luckily, there are other ways to onboard newcomers which you can use instead of, or in addition to, the 'good first task' approach. Here are six ideas.

FRAME First Tasks

The issues that end up getting labeled 'bite size tasks' are usually an eclectic mix. They're one-offs, and the work a maintainer does to prepare the task for a newcomer is only as useful as that one task.

FRAME first tasks are different. They're repeatable. That's one of the five key qualities that makes them ideal for new contributors.

The first two qualities are Abstraction and Modularity. Good first tasks don't require a lot of project-specific knowledge. They're abstracted away from the rest of the codebase. Often this is done intentionally through modular design. For example, a project I maintain called Parsons has over forty "connectors" to various third party platforms. Building a new connector requires understanding how the connector interfaces with the underlying codebase, but this is a well-defined and documented interface. Because the interface is well-defined, that makes the task Explainable.

Which brings us back to Repeatability. Writing up a newcomer-friendly, comprehensive explainer about how to build on the well-defined interface is a lot of work! It only makes sense to do if the task is repeatable. Luckily modular designs lend themselves to being extensible. Often people can continue adding new features through the interface for months or years to come.

Finally, it's worth flagging that these kinds of changes tend to be Feature additions. Bugs by their nature tend to penetrate abstractions in hard to explain ways, which makes them hard to FRAME.

In summary, we want tasks that are:

• Features
• Repeatable
• Abstracted
• Modular
• Explainable

To learn more, see my Guide to FRAME First Tasks.

Context-Building Tasks

As I've mentioned several times already, newcomers do not have project-specific knowledge. They lack context. But if we want them to eventually become regular contributors, they're going to need to learn that context.

Context-building tasks are tasks which don't require lots of knowledge to do, but help you gain knowledge through the act of doing them. They help contributors learn more about the codebase, the community, or both. This makes them ideal for people who are already onboarded enough to know they want to stick around.

For example, asking newer contributors to do issue triage exposes them to the types of problems that come up in the codebase and the way that the community handles fixing those problems. As long as there's a more experienced team member around to review their work, it's okay if they can't triage everything correctly. They can do their best and learn over time. Similarly, asking new contributors to join the pull request review team can expose them to the codebase and help them build up context.

Newer contributors can be genuinely helpful in these roles! They may not be able to catch everything, or handle edge cases, but they can address immediate problems like missing information in an issue report. They can also help reduce response times. People reporting issues and submitting PRs ofen appreciate a quick response from the community, even if it's not a complete response.

Other context-building tasks include writing release notes and user-facing release summaries and documenting community activities like note-taking at meetings or summarizing mailing list activities.

To learn more, see my Guide to Context-Building Tasks.

Onboarding Tasks

There's a type of task that newcomers are actually better suited to tackle than anyone else: onboarding tasks.

It's really hard for an experienced member of the project to spot gaps and flaws in new contributor guides, set up guides, basic tutorials, and other onboarding materials. Long-time contributors have a ton of implicit knowledge that fills in those gaps without them even realizing. Similarly, long-time contributors already have development environments set up and dependencies installed, which means they might not catch missing steps in a setup guide. Even if experienced contributors could accurately re-create their beginner mindset when writing and reviewing these materials, they'd still only represent a portion of the possible perspectives new people bring to a project. Everyone's background is different, so adding new perspectives is always valuable.

You can ask new contributors to go through the various guides and tutorials your project uses and flag anything that confuses or blocks them. This is itself a valuable contribution, but you can also work with the them to make the necessary fixes.

Many years ago, Deb Nicholson and I ran an event called 'SpinachCon' where projects ran newcomers through their contributor onboarding materials. You can learn more about how we structured that and the materials we used here.

That guide also describes how we helped projects do new user experience testing. That's a bonus idea for tasks newcomers could help with!

Embrace Contributor Skills

Newcomers lack project-specific knowledge, but they are rich in many other kinds of knowledge. Sometimes that expertise can be exactly what a project needs!

It's easy to look at an open source project and assume that the primary kind of help they need is technical. After all, it's a software project. But coding is almost always the one thing that open source projects already have capacity for. They may not have enough capacity. They may really want more code contributors. But they usually have at least one code contributor in the form of the lead maintainer themselves.

But there's so much more to an open source project than coding. Maintainers are often asked to do a variety of things they may have no experience with, from project management to community management to user support to documentation writing to teaching and mentoring. The bigger a project grows, the more diverse their needs become. Projects need help with user research and design, marketing and publicity, governance and conflict resolution, legal advice, event planning, and more. My Visibility Spectrum Exercise highlights the many different kinds of work that might need to be done in an open source project.

Why focus so narrowly on coding tasks when newcomers may have deep expertise in areas that projects really need? Why not encourage newcomers to do design reviews, host events, draft social media posts, or help maintainers write grant proposals?

Some may protest, "But newcomers show up wanting to make code contributions!" That's not universally true. And to the extent it is true, it's a self-perpetuating cycle. People show up to open source projects hoping to make code contributions because that's the expectation we've set. People who want to make a user research or grant-writing or event-planning contribution often don't show up at all, because they assume they won't be welcome.

Pairing

Way back at the beginning of this post, I mentioned that newcomers can get discouraged if they're working on an issue labeled 'bite sized task' that ends up being way more complicated than expected. They might assume that they're too incompetent to handle something labeled easy.

You know who could correct that assumption right away? A more experienced community member who was pairing with them.

No matter how hard you try to make life easier for new contributors (including through some of my suggestions above, like FRAME First Tasks) they are going to run into challenges. Having them pair with another community member helps them learn from those challenges instead of being overwhelmed by them. It also helps build relationships. Even after the pairing session is over, that contributor will be more likely to reach out for help and support instead of silently giving up.

You can have new contributors pair on FRAME First Tasks, issues labeled 'bite sized tasks' or on anything else - the world is your oyster!

Let Them "Be"

I've just written a bunch of words on how to help newcomers make concrete contributions to a project, whether that's adding new features, improving onboarding docs, doing issue triage, or helping with tasks in their own area of expertise like user research or grant writing.

But in a way, this is missing the forest for the trees.

As I wrote in the first post on this blog:

What if newcomers don't contribute? What if they just...exist, without contributing? Why do we care so much that they contribute right away? Why is it so urgent?

The ability to simply be ourselves and feel good about it, without having to prove ourselves through achievement, is a cornerstone of psychological health. It is a hallmark of good relationships to be liked for who you are instead of what you can do. Unfortunately it's an ability that open source culture, and western culture in general, is constantly eating away at. (Have you ever reflected on the phrase "earn a living"? In our culture, you literally have to do in order be.)

This pressure doesn't just affect new contributors. It can be even harder on maintainers.

Unlike new contributors, who struggle to find things they can do, maintainers are often overwhelmed by things to do. There's more than they can reasonably handle. But, though the reason they cannot do the tasks is different, it's the same fundamental problem. Both the new contributor and the maintainer are faced with things they cannot do, and the guilt they feel over that eats away at their ability to simply be. The new contributor feels like a failure and leaves the project. The maintainer feels like a failure, and burns out.

It doesn't have to be like this. We can create communities that celebrate being just as much as doing.

What if instead of encouraging newcomers to "contribute", we simply befriend them? Chat with them in our forums and matrix channels, invite them to social events, learn about them, tell them about ourselves - build relationships with them.

Then, whenever they are ready to start contributing, they will be so much more resilient to all the challenges that contributing throws our way. They will have real, solid relationships to call on for help.

And in the mean time, their simple presence is a boon to the community. As a maintainer, I've had my life made better and my work made easier by a community member offering to hop on a call and co-work with me, or sharing a funny meme to break the tension when I was frustrated by something. Those people help me not burn out. I'm so glad they didn't decide to leave because they couldn't make a code contribution.

In the end, the most important thing you have to contribute to a project is yourself.