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

stop. think. start again. (was Re: Poor State of the Man Pages)

From:
Stas Bekman
Date:
November 28, 2003 14:01
Subject:
stop. think. start again. (was Re: Poor State of the Man Pages)
Message ID:
3FC7C660.9050008@stason.org
Shlomi Fish wrote:
> My friend ...

Shlomi, is it possible that your friend is you?

Just kidding ;)

But seriously, you don't want to make enemies with the very people who decide 
whether to commit your contributions or not. With every post on the line you 
have taken now, your p5p karma is exponentially decrementing. Probably it has 
already passed 0 and heading into a deep minus. Once you are in minus, it will 
take a hell of an effort to get yourself above zero. People will simply ignore 
your posts, without even trying to see whether they are of any use.

Before you come out with any big suggestions you need to gain that karma by 
working hard and contributing a lot. You don't have to be a core C programmer 
or understand perl guts to be a great asset to the perl community.

As someone who wrote a lot of docs in the last 5 years, if you will allow me 
to give you an advice, it's really easy to improve docs incrementally by just 
watching discussions on this list, beginners list, perlmonks.org and any other 
lists that you are hanging on, and post patches based on the threads that 
won't have been started if the docs were there, and fixing the gaps by making 
summaries of those threads and posting them here as patches to .pod files. 
Notice that you don't even have to participate in those threads, all you need 
is to be a good librarian.

The majority of the mod_perl 1.0 guide 
(http://perl.apache.org/docs/1.0/guide/) which is more than 1000pp worth of 
docs, was written just like that. People asked questions on the list, gurus 
have answered them, someone has summarized those threads and added them to the 
docs, so the broken records effect won't repeat again. It worked and still 
works perfectly for us, and you can do the same.

Take it in baby steps and you will get far...

As for gaining back your karma, stop this thread right now, don't post any 
follow ups which just turn into more flame baits. Not even to this email. Take 
a deep breath. Go over the p5p archives from the last week and see whether 
there was something discussed that is not (well?) documented well in .pods and 
post a patch fixing the situation. Once you are done, go to the week before, 
and repeat the process again. The cool thing is that you don't have to think 
about what should be fixed, others tell you that all the time.

Many times I don't have the time to write summaries, so I mark candidate 
threads as something that I'd like to be documented. and hopefully come back 
to them later. In fact I've a whole lot of docs to write, based on the recent 
input from TomC and NI-S about the intricacies of the IO stuff. I hope I'll 
catch up with those soonish.

Finally, it's being a good example that you are after, not volunteers. You 
want to be an example to other potential contributors. When people see that 
someone does a great job contributing, they want to do the same (who am I 
kidding ;).

__________________________________________________________________
Stas Bekman            JAm_pH ------> Just Another mod_perl Hacker
http://stason.org/     mod_perl Guide ---> http://perl.apache.org
mailto:stas@stason.org http://use.perl.org http://apacheweek.com
http://modperlbook.org http://apache.org   http://ticketmaster.com




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