develooper Front page | perl.perl5.porters | Postings from November 2003

Re: Shlomi's docs: Shut up and do it

From:
Shlomi Fish
Date:
November 28, 2003 02:20
Subject:
Re: Shlomi's docs: Shut up and do it
Message ID:
Pine.LNX.4.56.0311281216360.4392@vipe.technion.ac.il
On Thu, 27 Nov 2003, Andy Lester wrote:

> > A good idea to revitalize them and adapt them to our needs, would be to
> > start a Phalanx like project for documentation.
>
> I'm honored that you invoke Phalanx as an inspiration for this project.
>   However, there's one key part of Phalanx that you missed: I started it
> myself.  It wasn't a committee.  It wasn't me coming to p5p and saying
> "Hey, guys, let's start a project!"  I never posted to p5p about it
> until after I'd started it.  I just did it.
>

Hey, relax!

I was just posting the idea here to get some feedback. (not one of
incredibly good S/N ratio evidently, but still)

> > Namely, we:
> > 1. Collect user stories on what they did not understand in the
> > documentation.
> > 2. Assign volunteers to remedy these issues.
> > 3. Assign volunteers to go over sections of the man pages and try to
> > paraphrase them to make them clear enough.
> > 4. Collectively decide where the man pages could use some
> > re-organization,
> > and re-organize them.
>
> I think this is a great plan, except for one word.  Change "we" to "I".
>
> Stop arguing about it and DO IT.  If it's a worthwhile project, people
> will come on board and make things happen.  If it's not, then they
> won't.  It's the way open source works.
>
> I also suggest that you'll get better results without coming out with
> both barrels saying "The docs suck and need to be replaced."
>
> And I ask that the rest of p5p not bother squabbling about this.  Until
> there's some actual content from Shlomi's project, there's nothin' to
> really discuss.
>

Very well, I will.

Regards,

	Shlomi Fish

> xoa
>
> --
> Andy Lester
> andy@petdance.com, AIM:petdance
> http://petdance.com/ http://use.perl.org/~petdance/
>



----------------------------------------------------------------------
Shlomi Fish        shlomif@vipe.technion.ac.il
Home Page:         http://t2.technion.ac.il/~shlomif/

An apple a day will keep a doctor away. Two apples a day will keep two
doctors away.

	Falk Fish



nntp.perl.org: Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at ask@perl.org | Group listing | About