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.