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

[moritz]

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.

[adamsj]

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.

[Your Mother]

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.

[moritz]

(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.

[adamsj]

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.

[rir]

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