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. :-)
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 of how the module's functions fit in the real world, and how to get the best out of it.
There are many modules that do this very nicely, Richard Clamp's File::Find::Rule is a good example, it's long but does explain what it does very well. Others fail miserably, Ilya Sterin's XML::SAXDriver::Excel comes to mind. The documentation for XML::SAXDriver::Excel recently caused a big headache for a colleague of mine, simply because the documentation is both inaccurate:
(when the correct directory is XML/SAXDriver under your perl modules directory) and very unhelpful as to how to use it. Thankfully my colleague is reading Perl and XML to guide him, but without the book I personally wouldn't touch the module.(If you don't have a c compiler, you can optionaly place the file Excel.pm in the XML/SAXDriver/CSV directory in the perl include directory)
It's well known and accepted that programmers hate writing documentation, but if you want people to use your code you do need to have something that makes it clear why you should use it.
Whenever I write documentation or a review, I always get my partner to read it. She isn't a programmer and if she starts asking the wrong questions then I know I need to make the text clearer.
