japhb

Like many projects, Plumage wants as many active contributors as it can get. In order to bring in new contributors, any project needs to do a few things:

1. Get users interested in contributing (more on this another time)
2. Let them know how to contribute
3. Make it as easy as possible for them to do so

One big way to address that list is to invest in contributor (AKA "hacking") documentation. The word "invest" is intentional -- you will need to put quite a bit of time into writing the documentation, and you hope that it will bring enough additional contributions (that you wouldn't have otherwise gotten) to more than make up for the time you invested.

Hacking docs are over and above the low-level API documentation, covering object attributes, method signatures, exception types, and so forth. Those API docs will certainly make development easier for your contributors, but they don't capture the workflows, mental checklists, and rules of thumb that guide you when implementing new features or tracking down bugs.

For example, imagine you're working on a calendar application that handles culture-specific calendars and holidays. What are the tasks necessary to add a new culture to your application? Obviously you'll need to update the database of rules that determines start of year, groupings (such as weeks and months), day names, and so forth. And you'll need to add entries to the holiday tables for the top-level culture and all of its subcultures and local variants ... which means that you need to update the subcultures table too. All of these new values will need translations for the user interface as well. Did you remember to check if the minimum supported Unicode version needs to be bumped? And tests for both functionality and interface need to be written, and the QA lead notified of the test changes. Oh and then there's the cross-culture date translator ....

Faced with this kind of complexity, new contributors are likely to follow one of the following courses of action:

1. Give up and run away screaming.
2. Write a snippy blog post about how impenetrable your code is.
3. Spend an hour trying to figure out all the things they need to do, and then proceed to #1.
4. Produce a patch for the 50% of necessary changes they can actually figure out how to do, leaving you to try to track down what they missed.

This situation is, as they say, suboptimal. In a complex enough project, even the core committers are likely to forget tasks on a disturbingly regular basis if they try to keep the checklists in their head. And of course, every time a new feature results in a new task on the checklist, the change won't be communicated to everyone (and heavens forfend one of you is sick or on vacation for an extended period).

Thus, for your own sanity and that of your teammates present and future, an investment in proper contributor docs would be a wise decision. The fact that it will vastly improve your chances of recruiting and keeping new contributors is pure profit.

Of course, there's the small matter of actually investing all that time. If you try to sit down and write all of it at once, you'll probably choose action #1 and run away screaming ... which is why it pays to do it a little at a time, as you go. You'll be surprised how much useful documentation you can produce when you write it in little pieces.

Over the last couple weeks, I've made it a personal policy that any time I work on a Plumage task I've done more than once, I document the procedure in hopefully sufficient detail that anyone else can repeat it. A few times I found myself about to document something particularly bletcherous, and this forced me to fix the code or improve the process in a few places just so I could face the mirror in the morning with a clear conscience.

While I wrote these task-specific documents, I spent some time cross-linking the docs where one workflow related to another. Then I added a general Internal Design document to make it easier for readers unfamiliar with the code to find their way around. Finally, a general Contributing document lets new users know how they can contribute, and lists our (pretty minimal) rules.

I can tell there are quite a few more of these just waiting to be written, but already anyone should be able to add a new build tool, add a project action, or add a new plumage command within an hour of cloning the Plumage Git repository. That's a pretty good feeling. And the documentation work has already paid for itself by shining a light on some dark corners of the code.

But I'm still hoping to snag some new contributors too. :-)

Interested in our future progress? You can follow Plumage here or on twitter or identi.ca; or for the real time experience, come by #parrot and chat:

• https://blogs.perl.org/users/geoffrey_broadwell/ (atom feed)
• http://twitter.com/japhb
• http://identi.ca/japhb
• irc://irc.parrot.org/parrot