Beefy Boxes and Bandwidth Generously Provided by pair Networks
There's more than one way to do things
 
PerlMonks  

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

Title:
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!
  • 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
  • Outside of code tags, you may need to use entities for some characters:
            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?
    Username:
    Password:

    What's my password?
    Create A New User
    Chatterbox?
    and the web crawler heard nothing...

    How do I use this? | Other CB clients
    Other Users?
    Others chanting in the Monastery: (15)
    As of 2014-10-21 19:25 GMT
    Sections?
    Information?
    Find Nodes?
    Leftovers?
      Voting Booth?

      For retirement, I am banking on:










      Results (106 votes), past polls