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

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.
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

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.

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.

Staff Quality Deserves the Same Care as Software Quality

The Wikipedia definition of Continuous Integration (aka CI):

Continuous Integration aims to improve the quality of software…by replacing the traditional practice of applying quality control after completing all development.

The CI gurus in the audience will hopefully forgive me for criminally over-simplifying, but the process basically boils down to:

  • Commit early, commit often.
  • Automate tests, build and deployment.
  • You break it? You fix it. RIGHT NOW.

The key motivator in CI is right there in the definition: quality. Rather than waiting for the end of the production cycle to do all of the testing you do it in smaller increments throughout the project. The sooner you locate and correct potential issues the higher the quality of the finished product. This approach is proven for developing software, so why aren’t we also doing it when developing staff?

A typical methodology for managing professional development for a technical staff member is much more old school waterfall in nature:

Yearly review and feedback
  set yearly goals
    procrastination until just before next yearly review
      race to complete goals
        verification of goals in yearly review
repeat

OK, perhaps that was a somewhat snarky summary but I think we all recognize it as Standard Operating Procedure. How, really, does this process help anyone? No, don’t answer that; I’ll answer it for you: IT DOESN’T. By the time you get to the annual review, any sort of feedback is so much water under the bridge and far from actionable. Yearly professional development goals are reduced to the effectiveness of an open book midterm: crammed in at the last moment and generating a good grade but with no lasting value, either for employee, team or company.

Instead we should be approaching staff development and management with an approach incorporating the ideas of accepted software development methods like Agile and Continuous Integration:

  • Agile Professional Development:
    • Employee review cycles should be short sprints of a matter of weeks rather than months.
    • Professional development goals should be attainable and meaningful, each subsequent goal building upon the ones which came before.
    • Meetings for checking progress and providing feedback should be frequent, brief and informal. They also should be open, honest and egalitarian (managers need feedback as much as anyone).
  • Continuous Staff Integration:
    • New knowledge and skills gained through professional development should be committed back to the trunk (the team) for integration.
    • Staff development should be automated through empowerment, support, policy and culture rather than dictated by managerial fiat.
    • Notification of potential issues should be immediate and methods of correction should ideally be evident and obvious.

There are, of course, some potential drawbacks in rolling out a staff development process of this sort. The current “waterfall” model has been the standard for a great many years and has become ingrained in the operating manuals for many companies, affecting the ways budgets are written, compensation packages are structured, Human Resources offices are run, etc. It’s difficult to overcome this sort of institutional momentum.

In addition, this process has the potential to impose a hefty burden on tech managerial staff. The impact of yearly reviews for each staff member can be severe enough on a manager’s time. Without proper planning an agile and continuously integrated professional development method could become a fulltime job in its own right.

These drawbacks are not inconsiderable but they’re also solvable and worth the time to do so. It will take a lot of planning to be sure this process is rolled out in a way which makes the most sense for your organization, but as with any worthwhile change (say, to using Agile and a rapid release cycle), if done mindfully the benefits reaped more than repay the effort.