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/
5 thoughts on “Learning how to help people contribute to the PHP.net Project”
I’ve always been angry about the way bugs are dealt with – for instance, this one.
If I want to contribute, the bug tracker is a gateway drug; and if it doesn’t appeal to me, I get cranky
Some years ago I tried to help translating the manual to Portuguese but I just didn’t get used to dealing with all those XML, it was too boring, then I gave up after a few pages.
If it were some kind of web tool it’d be much better for newcomers. I recall some translation projects (on Launchpad I think) where you’d just translate the sentences on simple input boxes. Although I realize it’s much more complex than that for the whole PHP manual, I still think the XML way is not really optmized. Even for the guys already translating, it’d be much more productive some other tagless way.
I also remember a project going on to assist the documentation and translation but I just glanced now at the dochowto and the only thing I saw really different was SVN over CVS.
Or maybe I’m just too lazy :P
Yeah, I agree that translating the XML is difficult and admire the current translators for doing it. A movement towards PO (gettext) took place but it’s stalled. I love editing PO files for the reason you mention, as it’s much simpler. However, https://edit.php.net/ exists now which allows anyone to edit the files online. Still difficult, but a little easier.
That looks good. It seems I just translated pt_BR/language/oop5/inheritance.xml with an anonymous account.
However it’s not clear what’s gonna happen now. I assume it’s necessary that someone with SVN account commits it, right? Is it really going to happen? I mean is there somewhere this file is going to pop out as a pending commit or something?
If it’s this straight forward to translate I think I could help it more in my spare time at work instead of just sit watching lolcats.
By the way is it a top secret project? A Google search for link:edit.php.net strangely returns no result.
I wanna change this scenario with you.
Diogo Galvão, I’m brazillian too.