Is my familiarity with Perl and it's documentation blinding me to obvious flaws?

Yes. The best thing to do would be to take a look at the SOPW's and FAQ questions for the past three years1. See what kind of questions keep popping up. There's a disturbing pattern of similar questions. Those questions are the ones the documentation isn't answering in a clear and easy-to-find manner.

For one thing, I hate perldoc. With a passion. If I didn't have my 3rdCamel, I'd be up a creek. Plus, perldoc is almost never installed on systems that I didn't personally build. And, it depends so much on the terminal emulation - Exceed can screw up perldoc like nobody's business.

The second is that more and more Perl programmers are purely Windows-based. There are several Saints who have almost never programmed on anything but Windows. Yet, why are all the examples Unix? Why isn't there a set of examples, FAQs, and the like for each major OS? I'm pretty sure VMS is a bit different ... Well, File::Spec sure says it is. So is OS-X vs. OS-9 vs. ... you get my point.

The third thing is that terminology is tripping people up. A lot of questions I see in SOPW are ones where the answer often is perldoc foo. Then, the OP says "How was I supposed to know it was called 'foo'?!?". The true answer here is some sort of Google-like "Did you mean foobarbaz?" when doing some sort of search on this isn't right. In fact, it'd be really nice if Perldoc had a Google-powered search engine instead of the crappy one they currently have. And, I mean it's crappy!! I have done searches for Perl reserved words like, say ... do, and it's come back with everything but the manpage for do. What about searching for -X, which is how 3rdCamel calls the filetest operators? Nope, not gonna help you. And, you know what? I don't care about the differences between 5.6.0 and 5.9.1 ... I just want to find out what do's exact syntax options are! I know they haven't changed. Or, if they have, let me know in the manpage.

You know who's got a really good manual? MySQL does, that's who. Check it out and see what I mean. It covers every single version in one document, with user comments2. Some of those users are the developers. If there's a version dependency, it lets you know right there in the manual. Upgrade deltas are also covered, in the appendix. It's searchable and provides keywords first before anything else. And, it's easy to read - just like 3rdCamel. Why isn't our documentation like that?

  1. I'm sure there's a programmatic way to do this.
  2. These comments are a combination of wiki and blog-talkback. It's really neat.

Being right, does not endow the right to be rude; politeness costs nothing.
Being unknowing, is not the same as being stupid.
Expressing a contrary opinion, whether to the individual or the group, is more often a sign of deeper thought than of cantankerous belligerence.
Do not mistake your goals as the only goals; your opinion as the only opinion; your confidence as correctness. Saying you know better is not the same as explaining you know better.

In reply to Re: Reorganizing or fixing Perl's documentation? by dragonchild
in thread Reorganizing or fixing Perl's documentation? by BUU

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!
  • 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, details, 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, summary, 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.