hsmyers has asked for the wisdom of the Perl Monks concerning the following question:

I'm looking for good documentation and I thought to ask the monastery this simple question---What CPAN modules have the best documentation? Don't much care about the module itself, just the documentation...

--hsm

"Never try to teach a pig to sing...it wastes your time and it annoys the pig."

Replies are listed 'Best First'.
Re: Looking for Mr. Good Documentation!
by Zaxo (Archbishop) on Mar 08, 2003 at 02:31 UTC
    Inline, with Inline::C, has an excellent spread of pod documents.
    • In Inline and Inline::C, there are good examples of standard man style usage documentation.
    • For installation, configuration, and community info there is Inline-Support.
    • To assist those who are just getting their feet wet, there is Inline-FAQ and Inline::C-Cookbook.
    • For advanced needs, there is Inline-API, which covers how to write new extension languages, incidentally providing advanced support for the existing ones.

    After Compline,
    Zaxo

[reply]
Re: Looking for Mr. Good Documentation! (apropriately enough...)
by ybiC (Prior) on Mar 08, 2003 at 01:52 UTC
    I wouldn't necessarily say "the best" documention, but both Pod::Usage and Getopt::Long have documentation that are spiritually akin to Perl itself - easy to get started with, yet no dearth of depth.   So much so, that even a lunkhead like me easily figured out how to use them* with a degree of effectiveness.
      cheers,
      ybiC
      striving toward Perl Adept
      (it's pronounced "why-bick")

    * shameless plug

[reply]
Re: Looking for Mr. Good Documentation!
by grantm (Parson) on Mar 08, 2003 at 01:53 UTC

    That really depends on what you mean by good.

    Module POD is traditionally modelled after Unix 'man' pages: a terse synopsis to remind you of common usage forms; followed by a comprehensive reference section detailing options, method names and arguments, object models if appropriate, etc; and possibly some examples to close. From memory, the DBI documentation is a pretty good example of this genre (it's certainly comprehensive).

    Unfortunately, someone looking for tutorial-style material to get them started in unfamiliar territory is not likely to find this 'good'. The best documented distributions often have an 'Intro' document in addition to the reference docs. The Intro.pod document from the XML::SAX distribution is a good example. Perl also comes with a number of tutorial man pages like 'perlreftut' and 'perltoot'

[reply]

      I agree. Getting the right balance of tutorial and and reference/usage is a hard to do and good thing. I personally prefer that Tutorial documents are seperate (but present) and that Reference documents are clear and concise. I even hacked Pod::Html to add extra indexes so that I have a list of items mentioned in the document for quicker lookups.


      ---
      demerphq


[reply]
[d/l]
Re: Looking for Mr. Good Documentation!
by gmax (Abbot) on Mar 08, 2003 at 14:52 UTC

    I am very fond of the documentation offered by Sean M. Burke in his modules. Check, for example, HTML::Tree and Tree::DAG_Node.

    In addition to the instructions on how to use the modules, he includes some articles covering the basics of trees, objects, and HTML scanning.

     _  _ _  _  
(_|| | |(_|><
 _|

    [download]
[reply]
[d/l]
Re: Looking for Mr. Good Documentation!
by perrin (Chancellor) on Mar 08, 2003 at 23:16 UTC
[reply]
Re: Looking for Mr. Good Documentation!
by Aristotle (Chancellor) on Mar 09, 2003 at 06:02 UTC
[reply]
Re: Looking for Mr. Good Documentation!
by Desdinova (Friar) on Mar 11, 2003 at 09:39 UTC
    I've gone as far as printing out the POD for CGI.PM and keeping it on my desk bookshelf with my other reference books
[reply]

      And that means the documentation is good or bad?

      Jenda
      Always code as if the guy who ends up maintaining your code will be a violent psychopath who knows where you live.
         -- Rick Osborne

      Edit by castaway: Closed small tag in signature

[reply]
        I meant it to say that it is good documentation, in so much that i have no need for "real" book for reference
[reply]

Back to Seekers of Perl Wisdom