in reply to Looking for Mr. Good Documentation!

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'

  • Comment on Re: Looking for Mr. Good Documentation!

Replies are listed 'Best First'.
Re: Re: Looking for Mr. Good Documentation!
by demerphq (Chancellor) on Mar 08, 2003 at 13:25 UTC

    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