I have been following this topic since it emerged on (I believe) the
mod_perl list. I continue to be interested in the project, but I am
afraid I don't find the goal to be stable enough for me to pick an area
and start development.

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 was working with another Perl developer at the time who had a better
comprehension of OO Perl and he was able to create working components
and through watching him I learned a lot, but at the same time I was
still frustrated because the documentation didn't cover what I felt were
routine task that were being accomplished, such as getting back the
attachments etc.  I haven't revisited that documentation to see if it
has improved, I am merely relating an experience.

I feel there are dozens of modules out there that fall into the same
category, extremely capable, but huge learning curve.

Documentation to me would be a good place to start and then at some
point moving on to wrapper modules that merely use the best of class
modules, but provide consistent method and class naming conventions to
the underlying modules.

The use of Perl at an Enterprise level already occurs, but what isn't
happening is a polished single voice.  I understand that in a sense that
is anti Perl, but Enterprises (read management) like professional
looking documentation with all the pieces fitting.  The fact that Perl
CAN do anything is lost to fact that this ability is not clearly
documented.

There are great efforts already in making the Perl documentation more
available, but we are still laking in an up to date single voice
repository with maintainers.

I am not however advocating that every single module be included, but
rather guidelines for documentation be created and currently popular or
voted for modules documentation would be rewritten with those
guidelines.  This is beyond our current list of common pod head
sections, but a break down as to what should be included under the
header, similar to what Sun has produced for the core Java classes.
Along with recipes, if you will, for using that module in conjunction
with other modules.  Another inclusion or appendix would be a glossary
of terms that are topic specific, but might not be known to people new
to a particular aspect of Perl or programming in general. (could just be
a more robust See Also section)

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 Johnson

Reply via email to