Public Lab Wiki documentation

Software Outreach

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)

Title Author Updated Likes
LibrePlanet talk: Sharing strategies for welcoming newcomers into FLOSS projects: First-timers-only, list moderation, and more @warren 5 months ago
Help Public Lab’s software grow by joining a supportive team @warren 10 months ago
Software outreach: Modularity is great for collaboration @warren 11 months ago
Software outreach: Codes of conduct and friendliness @warren about 1 year ago
Software outreach: a blog series @warren about 1 year ago

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.

Title Author Updated Likes
Public Lab Code of Conduct-Chinese Version @EdithCheung new contributor 18 days ago
Software outreach: Codes of conduct and friendliness @warren about 1 year ago
Communication Guidelines from the Wisconsin Grassroots Festival @mathew over 1 year ago



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:


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"!

Title Author Updated Likes
Create a welcoming "first-timers-only" issue to invite new software contributors @warren 2 months ago
BostonJS talks focused on welcoming new coding contributors @warren almost 3 years ago

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:

Title Author Updated Likes
Delhi Open source meetup at NSIT @tech4gt 8 months ago


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)

Friendly Bots

(coming soon)


Title Author Updated Likes
What are some examples you've seen of unsuccessful welcoming practices? @warren 9 months ago
Is anyone studying or writing about the rise in Codes of Conduct in open source projects? @warren about 1 year ago
Help with a standard mini-evaluation for assessing software outreach efforts? @warren about 1 year ago

Ask a question  or help answer future questions

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 joined a diverse group of community researchers and tapped into a lot of grassroots expertise.

Sign up