Re: My nomination for the worst sentence in Perl documentation ever

Replies are listed 'Best First'.
Re^2: My nomination for the worst sentence in Perl documentation ever by adamsj (Hermit) on Aug 21, 2008 at 14:54 UTC
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	[reply]
Re^3: My nomination for the worst sentence in Perl documentation ever by Your Mother (Archbishop) on Aug 21, 2008 at 15:31 UTC
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.	[reply]
Re^3: My nomination for the worst sentence in Perl documentation ever by moritz (Cardinal) on Aug 21, 2008 at 15:10 UTC
(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.	[reply]
Re^4: My nomination for the worst sentence in Perl documentation ever by adamsj (Hermit) on Aug 21, 2008 at 15:24 UTC
My apologies for any ambiguity in my writing: I did not mean your last sentence, but the last sentence that I'd originally quoted. Your response was perfectly polite and "you dummy"-free. They laughed at Joan of Arc, but she went right ahead and built it. --Gracie Allen	[reply]
Re^3: My nomination for the worst sentence in Perl documentation ever by rir (Vicar) on Aug 21, 2008 at 15:53 UTC
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	[reply]