Beefy Boxes and Bandwidth Generously Provided by pair Networks
P is for Practical
 
PerlMonks  

Comment on

( #3333=superdoc: print w/ replies, xml ) Need Help??

I will have to completely disagree here.

Perl itself comes with a huge amount of docs. I am sure it's harder to find your ways around it that let's say a CD player, but that's only because using Perl is a little more complicated than using a CD player.

And I am really unhappy with the sad state of the documentation for all VCR's I have ever owned by the way ;--)

I think enough people care about, and work on the core docs that it is quite comprehensive.</p

The problem is really with modules, as most of the time they are written, supported and documented by te same poor guy, usually better at (and more interested in) writing code than docs.

Plus the author is not necessarily the best person to write an introduction to a complex module. Things that seem easy and natural for someone who has written socket handling software for 10 tears might not be quite as natural to Joe Poor Perl Hacker who was writing COBOL up until last month.

So I think one of the best ways for module users to give feedback to the author is probably to write a piece on how they used the module, or just give some feedback on the doc.

I was documenting religiously and in great detail every single method in XML::Twig, until I realized through a random email on a mailing list stating that a potential user had given up after the first 2 screens (out of 22!). I needed to write a tutorial introducing the basics of the module (but more complex than the usual simple synopsis). Darn! But I'm really glad I caught that feedback. I hate coding stuff that will never be used because nobody looking for an easy way to solve a simple problem did not make it to the 44th method in the 3rd class of the module which was exactly what they needed.

So really I whished module docs were better and I think feedback could really help. But I'm happy with the core docs, thank you.

And stop killing trees and use perldoc, man and grep!


In reply to RE: RE: RE: The sad state of Perl documentation by mirod
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 perusing the Monastery: (2)
    As of 2014-09-20 17:27 GMT
    Sections?
    Information?
    Find Nodes?
    Leftovers?
      Voting Booth?

      How do you remember the number of days in each month?











      Results (160 votes), past polls