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

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 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 [cpan.org] 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 [cpan.org] recently caused a big headache for a colleague of mine, simply because the documentation is both inaccurate:

    (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)
    (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 [oreilly.com] to guide him, but without the book I personally wouldn't touch the module.

    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.