Public Lab Wiki documentation

Software Outreach

3,533 views | Last edited by warren about 15 hours ago | #15062

Since early 2016, Public Lab has worked to make our open source software projects more welcoming and inclusive & to grow our software contributor community in diversity and size. This page collects some of those strategies and initiatives.

We hope these will be useful for other free and open source projects as well. Please ask a question if you'd like to know more, and contact if you'd like to contribute a post. Thanks!


First, one thing we've learned is that doing good software outreach means acknowledging that your own work must change. Not only in shifting from direct coding work to organizing and cultural work, but also in transforming your own coding style and architecture (see Modularity, below) to make it easier for others to enter into your work and work with you. So, lessons we've learned are:

  • The code will have to change
  • Good outreach will make you a better coder!


Since 2016, we have learned from and incorporated strategies from other communties like the Hoodie project, SpinachCon,,, and Outreachy, and also shared our own ideas, and this session will cover a range of principles and strategies that have emerged across a number of separate efforts in different open source projects.

Read more about this on the Software Outreach blog series:

The complete series (so far)

Quick installation

There's more to say on this, but the very first thing we started to do at Public Lab to make our code more welcoming was to aggressively refine our installation process so that the whole system could be installed in 10-15 minutes. This took weeks of work -- cleaning up libraries, documenting, removing unnecessary parts, and above all testing installation on different environments -- but the real proof is posting a screencast video of installation on a freshly installed environment, like this one for Real-time video makes you honest! :-P


Codes of Conduct

An even more important counterpart to friendliness is to ensure people feel safe by clearly forbidding inappropriate behavior in a Code of Conduct, and by making sure people know the Code of Conduct and follow it.



As highlighted by the Hoodie community and the First-timers only movement, one of the first steps to having a more welcoming and inclusive community is to be really nice.

This can come through in documentation, in discussions, by providing positive and constructive support, and when thanking people for their work. Modeling and talking about welcoming and friendly tone is important to establishing and sustaining a welcoming culture for newcomers and long-time contributors alike.

Read more in this post:

Also see this mini study on emoji use!


As pioneered by the site and championed by Hoodie, we provide newcomers a chance to learn how we collaborate by going through a step-by-step guided issue to make their first contribution.

These issues take longer to make than fixing the actual bug, but the purpose is to engage with a new community member and show them how to work with us in an encouraging and supported way.

They are also small enough issues that they can be done in a fairly short period of time, and this encourages modularity (see below) -- complex, layered processes must be broken into smaller, simpler modules in a sequence, or there's "no way for others to enter the work"!

welcoming page

Welcoming pages

One key strategy adapted from Rasmus Praestholm of the Terasology project is to have a page specifically for welcoming and supporting newcomers, as shown in the screenshot above (Rasmus developed several Trello pages to help organize the welcoming process). This page is friendly, provides newcomer-specific resources and also features a call to action with #first-timers-only issues (see above).

See our Newcomer Welcoming Page here:

See our older version here, and create your own at:

(more coming soon)

Hosting events

Hosting local events is a great way to build out a local coding community -- as demonstrated impressively by @stella of Rails Girls Nairobi -- read more here:


Modularity may sound kind of boring as a topic -- and it's relationship to outreach and onboarding not immediately apparent. The basic idea is to isolate functionality in smaller chunks of code which are easier to reuse, understand, and maintain.

But this is exactly what newcomers need -- to not have to know a much larger whole system to be able to get your bearings, and to know what a chunk of code will receive as input, and should generate as output. It also makes for very test-able code, and code which has a minimal "entanglement" with other parts of a complex system.

I encourage ANYONE doing open source work to think hard about how their project can be better modularized -- along with the various other strategies on this page, it can lead to a major influx of new contributors!

Read more here:


How can we understand what's working and not working in our efforts to welcome a broader and more diverse group of contributors into our community? Evaluation techniques are critical to understanding what we're doing poorly and what's working.

Read some about our work in evaluation on this page, and read about our Software Community Survey here

(more coming soon)

Ladders of participation/leadership

Once you've gotten a lot of people to take their first step in contributing, what's next? We ask new contributors, once they've taken the initial step, to create their own first-timers-only issues. After all, they're now experts in being first-timers!

Community Toolbox asks people to take the next step by writing their own.

(more coming soon)

Social media outreach

Social media outreach can be a surprisingly powerful way to recruit people, by making them feel truly welcome, encouraged, and -- once they've made a contribution -- thanked! We're learning to do this better, but thanks to efforts like for helping to get out the word on social media.

(more coming soon)

Continuous integration

This is obvious to some, but using a continuous integration testing service like TravisCI can be a crucial way to support newcomers. TravisCI and Dangerbot provide immediate helpful feedback to new folks who open pull requests:

But there are things to look out for -- like ensuring automated messages are themselves friendly and encouraging, not harsh and intimidating. Language matters!

But the key here is that people can share what they've got done so far, and ask for help early. We encourage folks to open a PR as early as possible so other community members can "look over their shoulder" and offer support. Some issues can be solved without even installing a project locally (scary!).

(more coming soon)

Fellowship & funding programs

We participate in several and there are lots out there!

Friendly Bots

We use Welcomebot and First-Timers-Bot to great effect at Public Lab code projects, and you're free to copy our templates from here. Each plays a number of roles.

Welcomebot leaves a nice comment at three moments:

  1. when you open your first issue
  2. when you open your first pull request
  3. when your first pull request is merged

Each is an opportunity to a) be friendly and encouraging, b) offer resources and support, c) guide people through the process in a "trickle onboarding" way, so that they didn't have to face all the information up front, but could get it just when they need it, gradually.

I'll be writing more about this soon, but see this screenshot for the kind of welcoming moments we're able to provide using Welcomebot:

image description


A page for resources on outreach, diversity, inclusivity, and related topics!

Orgs and programs

Tools and resources


Ask a question  or help answer future questions on this topic

For a list of many features we've implemented for outreach efforts on the website, see:

Public Lab is open for anyone and will always be free. By signing up you'll join a diverse group of community researchers and tap into a lot of grassroots expertise.

Sign up