I heard about a very interesting way to attack this problem a couple of years ago in the Cocoon project. At one of the big cocoon user/dveleoper conferences (it could even have been at an apachecon) a small room of people with varying degrees of familiarity with the source code worked collaborativly for a stretch of about 6 hours to clean up the top 100 issues facing cocoon, including tons of documentation.
The proceedure was very simple but needs some tools.
Ingredients:
- 1 projector to display the list of issues for all to see
- some developers with commit rights
- 5 x that many other people willing to collaborate
- everyone needs an apple mac and SubEthaEdit (collaborative text editor) and iChat.
method
- small teams (max 6 including the key-dev ala the dinner party principle) rally about a developer with commit rights - the key-dev as i shall call her - and choose an issue to address.
- key-dev opens master copy of code in SEE and other developers connect to that via bonjour.
- everyone makes changes / be they code, javadocs, useage docs or whatever.
- using ichat's status indicators to show others if you are still working or done with your specific changes.
- when all done key-dev saves / builds / tests etc
- fix any new issues that have emerged from this cycle
- when done key-dev commits to SVN and the team is free to disband and form a new team, or just keep on going with another issue.
I use the term swarm development to describe this approach and after hearing about it from an apache mate we tried it within my old workplace where many of the developers used macs. it was quite astounding how quickly issues, especially documentation issues were nailed.
My suggestion is to coordinate a maven users / developers conference somwhere where the weather is nice (I hear the April sun in Cuba is nice) and we all collaboratively fix as many of the outstanding documentation issues as we can.
iChat and SEE work over the wider internet too but there's nothing quite like having a bunch of people in a single room attacking a set of problems at once. the vibe is intense.
Kind regards,
Dave Sag
"Brett Porter" <[EMAIL PROTECTED]> wrote on 07-03-2006 04:14:18:
> I tihnk you both make pretty good points on this, even where you might
> agree to disagree. Unfortunately I don't have time to reply to this
> entire thread, but I couldn't resist this point:
>
> On 3/7/06, Brian K. Wallace <[EMAIL PROTECTED]> wrote:
> > >
> > > And fourthly, the developers are often *not* the best people to write
> > > the documentation. For someone who knows all the details of an
> > > implementation it's quite hard to step back and write good introductory
> > > tutorials.
> >
> > On a roll here - although I'd replace "often" with "definitely". What
> > would be truly beneficial would be to have someone IN CHARGE (as much as
> > certain people are "IN CHARGE" of certain parts of the code) of
> > providing USER documentation for each release. A developer? Sure. But
> > NOT a core developer that "just knows".
>
> All you are talking about here is a contributing user. There is
> nothing stopping any user making that transition, and it would be
> welcomed - in fact, the minute we find one we'll hold on and never let
> go. It's rare for people to only contribute to documentation, and the
> couple who have volunteered to do so in the past have either ended up
> preferring to code or getting burned out on it very quickly.
>
> By the way, in our projects, its rare for anyone to be in charge for
> anything code or documentation. The whole project is responsible for
> everything, and people do what they have to for their work or itches
> as time allows. As a project, we try and direct people with the
> capacity to the right areas.
>
> Now, we do know there are missing pieces of documentation, and are
> correcting that over time. It's also my personal vendatta to write
> docs for new functionality at least going forward, and even if they
> are brief so that people can expand on them easily.
>
> The key point of this all was that it is impossible for developers to
> know exactly where the holes are now. Rants about documentation are
> not going to change anything - *we already know* it needs work, and
> always will need work, as you've both said.
>
> But there are many ways you can contribute:
> * file a bug for specific documentation problems. Even if you don't
> know the answer, say what you couldn't find or couldn't understand.
> * pick up a bug and research that single topic and write a doc for it.
> * put together outlines for other people to flesh out.
>
> As for the wiki, we consider that a workspace. Please use it if you
> can, and suggest ways to integrate it into the site if you find uesful
> things there. Patches are best - APT is no harder to write than wiki
> markup.
>
> Thanks for your concern!
>
> - Brett
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: [EMAIL PROTECTED]
> For additional commands, e-mail: [EMAIL PROTECTED]
>
