While exploring ways to improve how the PHP project finds and teaches new contributors, I wondered how other projects do it so started the process of evaluating several. So far I’ve fallen in love with the Ubuntu approach because they offer a ton of information and promote it well. The PHP project does neither of these things… Fail!
Unlike PHP.net, Ubuntu.com prominently displays “Get Involved” on their main site. This area clearly breaks up into different categories like Bugs, Brainstorming, Design (UI), Support, Localization, Testing, and the two I’ll focus on: Development and Documentation.
The Documentation section
- Intro: Introduces what the documentation team is all about
- Projects: The different forms of documentation
- Style Guide: How the wording should be written. Third person? Is it then or than? That sort of thing
- Meetings: Log of past discussions, and information about future ones
- Contact: How to get in touch with documentation team
- Sub-pages: Navigation to various other parts of the HOWTO
The page is clear, concise, and either directly explains a topic or links to it. A few minor concerns are:
- Navigation: Are the Wiki links clear or is a more friendly TOC possible?
- Getting the source: It was not friendly to a bazaar dummy like me but eventually I figured it out
- Information overlap: Nothing major, but some pages contain the same info (something easy to do with Wikis)
The Development section
This area feels a bit more cluttered but all of the information we could possibly want is available, and eventually you’ll even stumble upon a chart explaining common routes people take as they become contributing developers, MOTU members, and eventually core developers. Not to say they are stepping stones to one ultimate goal (core developer), but they can be.
- Difficult to navigate: A lot of information scattered about
- Scattered linking: Links refer to different parts (domains) of the site, so it’s easy to get lost
- Information overload (is that bad?)
Although the main “Get Involved” page doesn’t link to it, there is a detailed area titled ContributeToUbuntu that lists about every possible method a person could take to help the Ubuntu project. This includes marketing, donations, handing out CD’s to friends… everything. I like this section.
The Ubuntu Brainstorm area is also worth checking out and I’m curious what sort of ideas and brainstorms the PHP community would come up with and vote for. Some good [and bad] ones no doubt.
Still more evaluating and idea gathering from other projects to do but it’s clear we over at PHP.net have a long ways to go. Basically, we suck at marketing and follow the chaotic old boys club mantra of throwing people directly into the fire and we even force them to light their own match. But, at least we do allow any and all humans to join this club.
So although it’s beautiful how something like PHP can result out of pure randomness and chaos, and although it’s possible this approach has benefits like forcing people to communicate heavily with current members, the drawbacks likely outweigh any potential benefits.
How I’ll help change the situation and beyond
While doing this I also decided to make it my life mission, or at least one of them, to help create a resource generic enough to help all Open Source projects create useful guides for getting involved. Eventually each component will be broken down and offered for common use (and open editing) and available for anyone interested. For example, if your project uses CVS then this guide will offer a blurp of text that explains how to get started using it for a specific project. Project X takes it, modifies, and we’re all happy and contributing. More on that later but creating this specifically for the PHP project is the initial and primary goal today.
If you know of a project that handles this topic well then please write about it here or privately via the contact form.
April 2 update: Stumbled upon this today, it holds a lot of promise: http://teachingopensource.org/