Beefy Boxes and Bandwidth Generously Provided by pair Networks
go ahead... be a heretic
 
PerlMonks  

My nomination for the worst sentence in Perl documentation ever

by adamsj (Hermit)
on Aug 21, 2008 at 14:17 UTC ( #705799=perlmeditation: print w/ replies, xml ) Need Help??

From perldebug.pod:
w expr
Add a global watch-expression. We hope you know what one of these is, because they're supposed to be obvious.
They laughed at Joan of Arc, but she went right ahead and built it. --Gracie Allen

Comment on My nomination for the worst sentence in Perl documentation ever
Re: My nomination for the worst sentence in Perl documentation ever
by moritz (Cardinal) on Aug 21, 2008 at 14:29 UTC
    If you don't like, send a patch to p5p. Usually helpful doc patches are applied without much fuzz. (If you don't know what a watch expression is, send a bug report instead).

    Improving stuff should always be preferred over bragging about them.

      How do you feel about the tone of that sentence? Does it sound as though there's a silent "you dummy" at the end?

      I think I will send in a patch. But how does one patch the attitude that leads to sort of unhelpful--no, actively hostile--documentation in the first place? How can you tell someone "RTFM" when the FM is FU?

      I had no trouble writing a watch expression that worked correctly, even with the lousiness of the documentation.

      However, since the expression I was watching for took some time to show up, I was sitting there for a long while wondering, "Did I do it right?" Not exactly how you want to start a morning with a production system in a bad state.

      They laughed at Joan of Arc, but she went right ahead and built it. --Gracie Allen

        (updated a bit since I wrongly remembered what my "last senctence" was)

        How do you feel about the tone of that sentence? Does it sound as though there's a silent "you dummy" at the end?

        I hope not.

        But how does one patch the attitude that leads to sort of unhelpful--no, actively hostile--documentation in the first place?

        You can't patch people or attitudes.

        Ironically you displayed a rather similar attitude by not being helpful, IMHO.

        Does it sound as though there's a silent "you dummy" at the end?

        No. Short bits of writing are often tone free so the emotional reaction one has to them usually has more to do with the reader's state of mind than the writer's intent. If you figured it out with that doc, you're obviously not a dummy. :) I'd have to keep looking for an example or a better explanation before I could write one but I wouldn't feel dumb, just annoyed.

        Given that you had no trouble writing a [correct] watch expression, it seems that the documentation was fine. It is impossible for the authors' of the debugger to anticipate the speed of your code.

        I've never used "watch expressions" nor the perl debugger and I don't find any insult or hostility in the quoted documentation.

        Patches for peoples' attitudes are submitted all the time, but only the possessor of the attitude can apply the patch.

        Be well,
        rir

Re: My nomination for the worst sentence in Perl documentation ever
by dragonchild (Archbishop) on Aug 21, 2008 at 15:47 UTC
    If you use a debugger, they are obvious. If you don't use a debugger, then read Wikipedia or gdb's documentation. If you still don't get it, then you're kinda screwed and shouldn't be using a debugger.

    In other words, the documentation is expecting you to be a relatively intelligent person. Sorry if that doesn't give you a warm fuzzy.


    My criteria for good software:
    1. Does it work?
    2. Can someone else come in, make a change, and be reasonably certain no bugs were introduced?
      the documentation is expecting you to be a relatively intelligent person.

      OOh! That is soo wrong.

      Who should I select? Um. How about Kofi Annan; or Alexandra Kosteniuk; or Thomas C. Schelling; or Steven Hawking; I wonder if any of them are intelligent enough to have used a debugger?


      Examine what is said, not who speaks -- Silence betokens consent -- Love the truth but pardon error.
      "Science is about questioning the status quo. Questioning authority".
      In the absence of evidence, opinion is indistinguishable from prejudice.

        If they have a need to read the debugger's documentation, I presume they have some degree of interest in the subject, yes.

      Even if you came into this as an intelligent but inexperienced person wanting to learn more about debugging in Perl, wouldn't you rather see "Don't know what this is? Look for a general debugging tutorial" than "We hope you know what one of these is, because they're supposed to be obvious."?

      One of the issues here is that perldebtut has placeholders in for the section discussing this. I think I shall submit a patch.

      No, the documentation is expecting you to go read some other documentation to answer a perfectly reasonable question, and doesn't even have the courtesy to tell you where that documentation is. Certainly most Perl programmers with any degree of experience can probably work it out, even if they haven't used that debugger feature before, but that logic applies to a lot of things that are, nonetheless, extensively documented—which I've always regarded as a feature of Perl's documentation, to be honest.



      If God had meant us to fly, he would *never* have given us the railroads.
          --Michael Flanders

Re: My nomination for the worst sentence in Perl documentation ever
by dwm042 (Priest) on Aug 22, 2008 at 17:25 UTC
    I tend to mistrust the phrase 'obvious' because it is abused in the academic world, especially by mathematicians.

    For one, if something is obvious, then it can be easily explained. But then there is the phrase 'intuitively obvious' which is a classic academic canard. The people using this tend to be dealing with a problem that isn't obvious at all, has many edge cases and is tedious to explain. So they call it 'intuitively obvious' and move on to something they would rather talk about.
Re: My nomination for the worst sentence in Perl documentation ever
by repellent (Priest) on Aug 28, 2008 at 17:45 UTC
    My take is that documentation (Perl or others) should be kept professional and at a neutral-tone, with many useful examples.

    That's not to say that we should cut out all sentences that seem to be passing a "personal message" to the reader. If the intent of the sentence is to be helpful (not in a smart-alecky way), then leave it in.

    If the sentence is redundant, as italicized in the OP, then cut it out.

Log In?
Username:
Password:

What's my password?
Create A New User
Node Status?
node history
Node Type: perlmeditation [id://705799]
Approved by friedo
help
Chatterbox?
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others making s'mores by the fire in the courtyard of the Monastery: (4)
As of 2014-10-21 00:50 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    For retirement, I am banking on:










    Results (94 votes), past polls