In The Cathedral and the Bazaar, Eric S. Raymond makes the case that "with enough eyes, all bugs are shallow." It's a good sentiment, but as a new project spins up, getting and keeping enough eyes can be hard. You've got your first swing at the project up on GitHub; you've been promoting it and have some new contributors coming around. Now, how do you keep them?
In his OSCON presentation, Optimizing your project for contribution, Joshua Matthews, a platform developer at Mozilla, gave a five-step plan for making sure that new contributors have a positive experience when joining a new open source development project.
1. Prioritize useful information
Having a wiki with information that the new contributor will need close at hand is a fantastic way to do this. Make sure that you answer the crucial questions of "How do I use it?" "How do I change it?" and "Where can I get help?" on pages right up front. Use links to get into deeper technical information.
For more advanced contributors, a roadmap and recommended workflow are good ideas, as is a document describing requirements for acceptance of contributions. Nadia Eghbal created an excellent template for contribution guides that is licensed CC0, so you can use it freely for any purpose.
For experts, consider documents like a changelog, FAQ, release notes, and pull request templates.
One thing you should never do is send them to your bug tracker. Saying "Find something to work on in the bug tracker" is one of the fastest ways to chase off a new contributor. Bug trackers can be full of technical jargon and cultural or domain-knowledge buzzwords that the new coder cannot decipher. Some issue trackers, like the one in GitHub, let you tag some issues as suitable for newcomers, and you should absolutely use those!
2. Reduce friction
If your project has lengthy install instructions that don't work, you'll drive people away very quickly. A better idea is to use an install script. Also, while it's a lovely idea to be able to hack on your project on any platform at all, specifying a standard coding environment will help the newcomer get involved quickly. Coders who want to work on non-standard platforms will either be expert enough—or determined enough—to figure out how, and many of the rest will choose to use the standard.
Automating notifications to your core team of new contributions is also a friction reducer; it helps with quicker responses, which encourages the contributor to keep learning and working.
3. Make your expectations clear
You can make new contributors quite a lot happier by using your prioritized documentation to make your expectations of new team members crystal clear: what do they need to know? How long should it take to get or give feedback? What are the project milestones and deadlines, if any? How difficult are the tasks they're being handed?
Another important expectation is to let your contributors know what behavior is acceptable to the community. For this, a code of conduct is a really easy way to make it clear. Numerous templates and examples exist online, so you don't have to write it from scratch.
4. Respond appropriately
Always make sure that the time required to give feedback is minimized. There are few sensations worse than waiting around to hear back, particularly for a first-time contributor. If the change doesn't meet the standards of the team, don't just dismiss it outright. Be sure to shepherd it along to completion that is up to scratch. Always explain why a change might not be desirable, and be sure and thank them!
When you're working with a new contributor, watch out for weasel words like "just," "easy," and "simple." While the task might be easy for you, it's not necessarily so for them, and that belittles their effort. Make sure they know they can ask questions and follow up with a question like, "Does that make sense?" as it gives them opportunity to ask clarifying questions. In talking about the team, use inclusive words like "we" and "our".
5. Follow through
Always be sure to publicly recognize your new contributors. An email to the team list, an announcement on the IRC, or a commit adding them to a list of contributors in the project documentation will build them up and encourage them to stay with the team. Always remember that every contributor is a potential maintainer or release manager.
A few structural things set up early in your project lifecycle can help contributors for a long, long time. Some of these things are somewhat time-consuming, and some are simple courtesy. In the long run, you may find that all of them are worthwhile to the vitality of your contributor community.
Comments are closed.