Beefy Boxes and Bandwidth Generously Provided by pair Networks
Just another Perl shrine

Comment on

( #3333=superdoc: print w/replies, xml ) Need Help??
Generally, there are two types of documentation:

1) Stuff that tells you how to do things. This assumes that you know what you want to do in the first place ("Hmmm - is the recurse option on chmod -R or -r?"). We call these "reference manuals" - the Camel book is a fine example of such a beast.

2) Stuff that tells you what things to do. This means you have an understanding of the end result that is needed, but not sure of the way to do it. The "Perl Cookbook" is a fine example of such a manual. These are far more useful for use beginning programmers.

But - much of perl's power lies in the great array of modules that are constantly being developed. The documentation of these varies from wonderful to woeful. But, what is missing is an extension of the 'how to' approach to incorporate these modules. For example, how many of the questions posed here are answered by:

You should use module Foo::Bar::WDNNS_Documentation

Now maybe that is what more attention needs to be focussed on. There are lots of resources on the web - merlyn's Web techniques column is one that immediately comes to mind. At least the experts here can regularly point us to such sources.

In reply to RE: The sad state of Perl documentation by Maclir
in thread The sad state of Perl documentation by SuperCruncher

Use:  <p> text here (a paragraph) </p>
and:  <code> code here </code>
to format your post; it's "PerlMonks-approved HTML":

  • Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!
  • Titles consisting of a single word are discouraged, and in most cases are disallowed outright.
  • Read Where should I post X? if you're not absolutely sure you're posting in the right place.
  • Please read these before you post! —
  • Posts may use any of the Perl Monks Approved HTML tags:
    a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr
  • You may need to use entities for some characters, as follows. (Exception: Within code tags, you can put the characters literally.)
            For:     Use:
    & &amp;
    < &lt;
    > &gt;
    [ &#91;
    ] &#93;
  • Link using PerlMonks shortcuts! What shortcuts can I use for linking?
  • See Writeup Formatting Tips and other pages linked from there for more info.
  • Log In?

    What's my password?
    Create A New User
    and all is quiet...

    How do I use this? | Other CB clients
    Other Users?
    Others examining the Monastery: (2)
    As of 2018-01-17 03:49 GMT
    Find Nodes?
      Voting Booth?
      How did you see in the new year?

      Results (196 votes). Check out past polls.