copyright & licensing

all content © VM (Vicky) Brasseur and licensed under CC BY-SA

Open Source: Why Can’t We Just Make It Easy On New Contributors?

6 minute read

As an Open Source advocate I’m frequently asked to which projects I contribute. My answer is typically, “None right now.” Why is that? There are a few reasons but they mostly boil down to:

  • As someone who does not code often (or enjoy it immensely) I do not feel welcome.
  • It’s an opaque process.

For now I’ll set aside the first reason to focus on the second: the process is opaque.

From my point of view, there is absolutely no excuse for this. Wikis, CMSs and cheap hosting all make it abundantly simple to offer plentiful guidance to new contributors, yet somehow that guidance is rarely provided. New contributors must delve and divine and guess and pester in order to figure out where to start. It’s almost as though the community does this intentionally as a sort of rite of passage for new members. “If you can figure this out then you’re smart enough to become One Of Us.” This is incredibly arrogant and exclusionist.

Why can’t we just make it easy on people? Why can’t we spend a few hours writing some documentation and tutorials up front, guiding newbies along the community-accepted path of contribution? Long time contributors may find the concept of spoon-feeding new members offensive but doing so will not only bring in more people to the fold it will also raise the quality of the contributions from the get-go.

To demonstrate how a project can make it easier for new contributors I’m going to use the Perl project. This is not because it’s such a bad example of how to do things (it’s pretty good, really) but because I’m fond of Perl and want to make some suggestions on how to make it even better. Also, I know that the Perl community is generally friendly and open to ideas on improving community involvement. That said, most of the suggestions are more generally applicable to all Open Source projects.

First of all, kudos to Perl for having a dedicated Get Involved link very prominently displayed there at the top of every page of Perl.org! This visibility is a testament to the importance of contributions and contributors to the Perl community. Involvement is key for them and they put it front and center, right where it deserves to be.

However after that things get less obvious. The site is clean and well-designed, which is a pleasant change from many project pages, but this page is essentially just a list of bullet points with no context or meaning. For instance, what would I as a new contributor be expected to do with the Bugs, testing and reviews section? Is this for reporting bugs (yes) or fixing them (not so much) or…? What is meant by “testing?” Since I pay attention to happenings in the Perl community I know that this means automatically reporting test results to the imminently cool and useful CPAN Testers when I install new CPAN modules, but what if I were entirely new to the Perl world? I may think that “testing” implies a lot more hands-on work, perhaps testing new commits to the core language. It’s not obvious and it really should be.

The tagline of this page is Whatever your skill set or level you can get involved… While I believe this must be true, speaking as a mostly-non-coder this page does not make it obvious how I could get involved with the Perl project. Are there simple bugs I could fix (and if so, how)? Maybe documentation that needs writing/editing? How about project management? Ticket review? Marketing? Event organization? Donations? Not only are these subjects a good way to capture the less technical users and supporters of your project, they’re also a brilliant way for the new coding contributors to get a feel for the project and up to speed on the processes it uses.

Here’s a quick and dirty first draft of a version of this page which would be more useful to new contributors:

Whatever your skill set or level you can get involved…

Community

Some say CPAN is the strength and heart of Perl, but they’re wrong. The people are the heart of Perl.

Getting Started

Ready to dive in? Here’s how to do it!

Everyone
  • Contributor FAQ Every project has those questions which come up repeatedly. Collect them and their answers to help remove the barrier to entry.
  • An overview of the processes used for Perl. Link to another page. Key for everyone to know the steps in the process, not only so they’ll know what to expect but also so they’ll know better what language to use when asking for help.
  • Where to go for help. While this should be an element of every bullet point here, it also should be aggregated on a single page for ease of use. Broken down by subject. Include names whenever possible (mentors would be awesome and heroic). New contributors are more likely to ask for help if it’s obvious there’s a real person at the other end.
  • Where to find the documentation. Link to another page. List every form of docs that exist. Keeping all this in one place drastically reduces frustration for new contributors.
  • Where to find the code. Link to another page. Not just where to find it, but how to get a copy and, if you wish to commit, how you’d go about doing that (including expected code style).
Non-Coding
  • Review and rate – the CPAN modules you use.
  • Send automatic reports to CPAN testers every time you install a new module.
  • Review trouble tickets. Link to a page describing the process, requirements and expectations for reviewing project trouble tickets. Ideally will include a link to a list of tickets in need of review.
  • Write or edit documentation. Link to a page describing the process, requirements and expectations for writing or editing project documentation. Ideally will include a link to a list of documentation tickets.
  • Translate documentation. Link to a page describing the process, requirements and expectations for translating project documentation. Ideally will include a link to a list of translation tickets.
  • Organize or Volunteer at an event. Calendar/list of events (locations and dates), assistance required and whom to contact for more information.
    • Donate. Link to a donation page and/or page detailing whom to contact to give a donation.
      • Have another idea how you could help? Contact us! Link to the correct contact information.</ul>
        CPAN
      • Best Practices for coding for CPAN.
      • How to report a bug for a CPAN module.
      • How to contribute a fix for a CPAN module.
      • How to contribute a new CPAN module.
      • Contacting CPAN module maintainers and what to do if they don’t respond.
        Core
      • The Core Perl Development Process and Roadmap.
      • Read more about Core development.
      • Best Practices for coding Perl.
      • View or checkout the Perl 5 Core repository.
      • View the open bugs for Perl.
      • How to report a bug for Perl using perlbug.
      • Contributing a fix to Perl.
      • Whom to contact for more help contributing to Core Perl.

        Perl6

      Want to learn more about Perl6? Have a look over here! Anticipate the question rather than forcing it to be asked or searched for. </blockquote>

      Again, this is just a quick pass at a possible Contributors page, but as a non-contributor it’s much more inviting than the current, sparse version. I can easily look at this and see my options and the methods for performing them.

      Granted, there is a lot of organization and writing which would need to be done for a page like this to work. Believe me, I know it’s not easy getting all these ducks in a row. That said, I strongly believe that any project which goes through the steps necessary to make it much easier for new contributors to join will find its quality and reputation improving by leaps and bounds. It’s an effort very much worth making.