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. First, if you're interested in contributing as a first-timer, welcome! Please check out our welcome page at: > We hope these will be useful for other free and open source projects as well. Please [ask a question](#Questions) if you'd like to know more, and contact if you'd like to contribute a post. Thanks! ### Quick links * See [this post]( for the results of our 2019 software contributors survey (including demographic information) * See [this post]( for a presentation on these strategies as presented at LibrePlanet 2019 (with video) ## Transformation 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! ## Inspiration 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) [notes:series:software-outreach] **** ## 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 Resources: ## 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](/conduct), and by making sure people know the Code of Conduct and follow it. [notes:code-of-conduct] Also: - our introductory post about [Public Lab's CoC](/conduct) and [how we wrote it together](/notes/Shannon/07-06-2016/public-lab-code-of-conduct), packed with references, inspirations, and good advice - [Ada Initiative's How to Design a Code of Conduct for your Community]( ## Friendliness 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! ## First-timers-only 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"! [notes:first-timers-only-blog] ![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: [notes:coding-events] ## Modularity 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:** ## Evaluation 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](/evaluation), 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! * Rails Girls Summer of Code * Google Summer of Code * Outreachy * ## 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](/i/30267.png?s=o) **** ## Resources A page for resources on outreach, diversity, inclusivity, and related topics! ### Orgs and programs * * [Mozilla Diversity and Inclusion]( * Bridge Foundry (`@bridgefoundry` on Twitter) * NumFOCUS Diversity and Inclusion in Scientific Computing (DISC) - [mailing list](!forum/disc/join), [website]( * Rails Girls Nairobi * 500 Women Scientists (for possible outreach to scientific communities) * add more and help organize the page! ### Tools and resources * [DISCOVER Cookbook]( for inclusive events (NumFOCUS DISC Program resource) * OpenDemographics * - [@PublicLab]( ## System diagram Here is a system diagram of all of our welcoming systems, conventions, tools, and habits: [![plots2_Data_Model.png](/i/42841)](/i/42841?s=o) (from [this document]( **** ## Questions [questions:software-outreach] **** For a list of many features we've implemented for outreach efforts on the website, see: ...

Learn more »