Our main tech project, the Wiki Education Dashboard, is a free and open-source web application. Built with Ruby on Rails and React.js, it’s a codebase that started in late 2014 as an ‘agency’ project: we hired the firm WINTR to develop the software we needed. For its first year, it was almost exclusively built through full-time, paid development — with the exception of some language support features that were contributed early on by Wikimedia Foundation engineer Adam Wight. For our 2016-17 annual plan — with a much smaller budget for paid development — we wanted to explore the prospect of building a volunteer development community around the project.
We recently reached the milestone of 50 different contributors to the Dashboard’s code repository on GitHub — about 2/3rds of whom I would describe as newbies. Progress has been gradual and we’re still working on making the project better for newcomers. But this seems like a good time to reflect on what I’ve learned about running a newbie-friendly free software project.
Newcomer-friendly issues
The most important thing is to have some straightforward, self-contained issues lined up. This should come as no suprise to Wikipedians, who have been keen on the newbie-attracting power of typos and redlinks to missing articles for years. My advice:
- Identify specific, easily-understood issues that only require understanding one part of the system. Knowing where and how to start is often the biggest challenge with a new codebase, even for an experienced developer.
- Tag issues with the skills and/or technologies involved. This helps people find issues that they are confident enough to dive into. For the Dashboard, we use four categories for this: Design, HTML/CSS, Ruby/Rails, and Javascript/React. Some issues span multiple areas, but for first-time contributions especially, the fewer skills involved, the better.
- Refactoring and other code quality issues make great issues for newcomers.
- Document the knowledge you have about how to solve an issue. Which files need to be changed? Can you break it into several steps? Any good resources that would be particularly helpful?
Some of the biggest barriers:
- Getting a development environment set up is hard. Even beyond project-specific requirements, the diversity of systems, tutorials and ways of setting up particular tools means that some people run into trouble with getting MySQL, Ruby, Node.js, or some other core dependency. And when that happens, it can be very hard to debug.
- Javascript package management and build tools are complex and error prone. As of late 2017, the Javascript ecosystem seems to be settling down a little bit, but new and interesting environment-specific bugs still come up pretty frequently when newbies install all the assorted Javascript dependencies and build the project assets.
- For a complex project like this one, creating the local data needed to test and play with an issue is often harder than fixing the code.
Finding contributors
When it comes to attracting contributors, I’ve tried a lot of different things — and a lot of them have worked! We’re fortunate to be part of the Wikimedia technical community, which participates in things like Outreachy, Google Summer of Code, and Google Code-In — all of which have brought in great contributors. For several months, I focused on working with the AgileVentures community, which connects self-taught web developers with nonprofit tech projects. After the initial effort of getting to know the community and documenting our project, AgileVentures has become a steady source of contributions and contributors. I signed up for CodeTriage on a lark one day, more than two years ago, and recently connected with the first contributor who found their way to the Dashboard project from there. We’ve had contributions from people who use the Wikimedia Programs & Events Dashboard and want to scratch their own itch, and from dev bootcamp students assigned to contribute to an open source project. (I’ve also gotten lots of help from my local Ruby community, Seattle.rb.)
My tentative advice for finding contributors is to get the word out in a lot of different places, and take a long-term approach to helping new contributors get started whenever they show up. For the Dashboard at least, and probably for many similar web app projects that serve a particular community, nearly all the contributors got involved because of outreach efforts; waiting for contributors to simply show up on their own would not have worked.
The good and the bad
I’m really pleased with our progress on making the Dashboard a newbie-friendly project, and at this point I think it’s been worth the (very significant) time investment. But it’s not a short-term solution to getting more done — with most contributors I spend about as much time mentoring as it would take me to the same tasks myself, until they’ve spent a few months with the Dashboard codebase. Setting aside newbie-friendly issues can also increase the lead time between knowing about a problem and deploying a fix — especially for really easy things. But beyond the code contributions themselves, I’ve also noticed some more abstract benefits:
- I’ve started to think about code changes — bug fixes, new features, code quality improvements — in terms of how easy they are to describe, and to plan code changes in chunks that make each description as simple as possible. This leads to better decoupling of different parts of the codebase!
- I’ve also stopped thinking about the implementation in the friendlier parts of the codebase, freeing up some space in my head for other things.
- What makes the project easier for newcomers also makes it easier for experienced developers to get up to speed quickly.
- I learn a lot when I have to explain things!
Best of all, some people stick around and keep contributing to the project, and some (whether they stick around very long or not) have brought skills that I don’t have to the project. I’ve learned an enormous amount from volunteer contributors, and the codebase is much better for it.
Want to get involved with the development of the Dashboard? Let me know! Or send a general inquiry to contact@wikiedu.org.
Image: File:Hackathon at Wikimania 2017 – KTC 55.jpg, by Katie Chan, CC BY-SA 4.0, via Wikimedia Commons.
