[...] > For me one of the things that has been talked about and I would like to > work on when I have the time, is improved single voice documentation > that ties all of the popular modules and includes examples and comments > similar to what PHP has on its sight, but more robust and useful. > > The ability for anyone to publish their work is one of the great > strengths of the Perl community, but the weakness is the documentation > on some of the modules is weak and/or confusing to people that are not > developing with Perl everyday. I don't pretend to think we can make > Perl simple to implement for complex problems, but I do feel that we can > show how many of the existing stable/mature modules can be used to > perform various common tasks. > > My own difficulty with this stems from an incident I had with the > MIME::Entity module a year ago. My OO skill level just wasn't high > enough to implement a solution based on the documentation although I > could see the answer was there, it was just beyond my reach because the > authors documentation had assumed a less then surface understanding of > OO Perl. [...] > I know what I want in documentation, but I lack the patience and time > presently to put together a comprehensive example of what I am saying.
Aaron, if you want to change the way things are, *you* have to change them, not trying to push *others* to do the work for you. If every Perl programmer would contribute a little of their time to improve the existing documentation, we will achieve what you want. I'll give you a concrete example. You had troubles with the MIME::Entity docs, now you do understand how this module works. Have you considered patching the docs and submitting them to the author? I bet he will gladly accept your contributions. The actual "bump removal cycle" should be probably something like the following: - you don't understand how something works - you ask around and hopefully someone (author?) explains - now armed with the knowledge and understanding you implement the solution - you go back to the original problem, look at why you couldn't make it working in first place - you go the docs and patch them to make things clear so others who will follow will have no bumps on the road. - finally you submit the patch to the author It's all about individual contributions and not about guidelines. Guidelines are needed when there are many contributors and you want to regulate the way people are contributing to be more productive and consistent. If people aren't contributing what's the point of having guidelines? __________________________________________________________________ Stas Bekman JAm_pH ------> Just Another mod_perl Hacker http://stason.org/ mod_perl Guide ---> http://perl.apache.org mailto:[EMAIL PROTECTED] http://use.perl.org http://apacheweek.com http://modperlbook.org http://apache.org http://ticketmaster.com
