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 amarquis (Curate) on Aug 21, 2008 at 18:48 UTC
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.	[reply]
Re^2: My nomination for the worst sentence in Perl documentation ever by BrowserUk (Patriarch) on Aug 21, 2008 at 16:15 UTC
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. "Too many [] have been sedated by an oppressive environment of political correctness and risk aversion."	[reply]
Re^3: My nomination for the worst sentence in Perl documentation ever by chromatic (Archbishop) on Aug 21, 2008 at 18:40 UTC
If they have a need to read the debugger's documentation, I presume they have some degree of interest in the subject, yes.	[reply]
Re^4: My nomination for the worst sentence in Perl documentation ever by BrowserUk (Patriarch) on Aug 21, 2008 at 22:45 UTC
If it's their first time using a debugger, interest or not, they are very unlikely to know what a "watch" is in this context. It doesn't mean they lack intelligence, just specific knowledge. And that's when they are going to go looking at the documentation... 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. "Too many [] have been sedated by an oppressive environment of political correctness and risk aversion."	[reply]
Re^4: My nomination for the worst sentence in Perl documentation ever by jplindstrom (Monsignor) on Aug 22, 2008 at 13:04 UTC
If they have a need to read the debugger's documentation, I presume they expect the documentation to tell them how things work, not say "well, duh!". Intelligence obviously has nothing to do with prior knowledge. /J	[reply]
Re^2: My nomination for the worst sentence in Perl documentation ever by ChemBoy (Priest) on Aug 22, 2008 at 07:00 UTC
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	[reply]