Stories
Slash Boxes
Comments
NOTE: use Perl; is on undef hiatus. You can read content, but you can't post it. More info will be forthcoming forthcomingly.

All the Perl that's Practical to Extract and Report

use Perl Log In

Log In

[ Create a new account ]

ethan (3163)

ethan
  reversethis-{ed. ... rap.nov.olissat}

Being a 25-year old chap living in the western-most town of Germany. Stuying communication and information science and being a huge fan of XS-related things.

Journal of ethan (3163)

Wednesday October 30, 2002
02:57 AM

The need for clarification

[ #8678 ]

Here is an excerpt from a mail that I received this morning:

  > Oh, and a lot of people don't know about your mod, I barely found it
  > either, and the description makes some people think it's not as
  > powerfull as it is (Read only access to unix mbox). You really have
  > to read the docs to understand it. So I was thinking to write some
  > docs for you on my site and ask you to review them in a few weeks. I
  > have little spare time but I use it to write technical docs and
  > reference material. I'm pretty good at it with the examples I
  > provide so I think it would be a huge service to people trying your
  > module for the first time to see some examples from an intermediate
  > programmer like me. You guys forget your so far ahead of people that
  > your examples are difficult to understand. I was fine with your docs
  > though, I understand code much better since I learned PHP in addition
  > to my perl addiction. I didn't understand hash refs before but now I
  > can't stop using them.

I was thinking about the sentence "You guys forget your being so far ahead
of people that your examples are difficult to understand"
.

I think this chap has made a very justified complaint here. So what can CPAN
authors assume about the Perl skills of their potential users? I am always
tempted to include yet another example trying to foresee possible pitfalls
for novices or semi-novices - and thus annoying the more advanced users
who rather see the perldocs as a reference material.

And then, as this mail shows, there still seems to be need for even more
examples. Should we really re-iterate all those things that are layed out
in perlref? Should we explain the difference between an instance and
a class method?

I am not yet sure. I think from now on I'll always include a reference to
some relevant perldocs in the "=head1 SEE ALSO" section. After all,
it's always good to read the perldocs. :-)

The Fine Print: The following comments are owned by whoever posted them. We are not responsible for them in any way.
 Full
 Abbreviated
 Hidden
More | Login | Reply
Loading... please wait.
  • I can understand where the guy is coming from. There have been modules that I needed to use and understanding the docs can be hard work. There have also the modules where documentation has been rather sparse. It's not so much the idea of more examples that's necessarily needed, but more clarification of the problem that the module deals with and the solution(s) that it provides.

    In some cases modules jump in at the deep end and just give examples of the syntax. When what is actually needed is a description