Beefy Boxes and Bandwidth Generously Provided by pair Networks
Welcome to the Monastery

Re: grab bag of user questions

by tilly (Archbishop)
on Nov 04, 2003 at 19:35 UTC ( #304519=note: print w/replies, xml ) Need Help??

in reply to grab bag of user questions

My answer to the last question. I think that people should be encouraged subtly and unsubtly to rely their local documentation (accessible through perldoc). That is the only way to get documentation with any guarantee that its advice should match the version of Perl that you are using. Any version of Perl that they choose to document here will be wrong for a large fraction of users who might try to use it.

Replies are listed 'Best First'.
Re: Re: grab bag of user questions
by ysth (Canon) on Nov 04, 2003 at 23:39 UTC
    I have the feeling that perl documentation is more often updated to correct errors or clarify things than to match new functionality. It follows that newer doc will sometimes be a better choice even when using an older perl.

    But I think we would both agree that that pales next to the importance of training users to independently consult their documentation.

      If you believed the next version's documentation, here are errors that you would have had from various versions of Perl:
      1. In 5.003 you would have been left thinking that foreach my $var (@list) {...} should work, and would have wondered why it did not.
      2. In 5.004 you would have thought that you could use substr to replace text, not just extract it.
      3. In 5.005 you would have thought that our was a usable keyword and warnings was a usable module.
      4. In 5.6 you would think that you could have the new (and far more stable) threads implementation available.
      I have either had or seen people who had questions about every one of these. For instance take a look at RE (3): Should I use $ and $# ? which is from a thread here caused because someone who bought the third edition of the Camel tried to use our in Perl 5.005_03 and then got confused. See RE: Perldoc's vrs. Books, and RTFM's from around the same time period. Since then my opinion about the importance of local documentation has not changed, although I have a better understanding of why people have trouble understanding things sometimes.

      Now I haven't done any kind of survey to find out what kind of documentation patch is most prevalent. However my gut tells me that documentation far more often gets added than significantly rewritten. And added documentation is very often documentation added to describe new features which won't be there in old versions.

        <irony>But surely everyone knows about the major features added in versions they don't yet have.</irony>
        Noone ought to be obliged to know about the major features added in versions they don't yet have.
        However my gut tells me that documentation far more often gets added than significantly rewritten.
        I agree with that.

        OK, you've convinced me (but that doesn't mean I'm going to look for the most out-of-date documentation to link to.) Ok, you've convinced me that any link to online doc has not a lot of use beyond guiding the user to their local equivalent.

        (Update to dehumor and just say what I meant straight)

Log In?

What's my password?
Create A New User
Node Status?
node history
Node Type: note [id://304519]
and all is quiet...

How do I use this? | Other CB clients
Other Users?
Others about the Monastery: (16)
As of 2018-07-23 13:59 GMT
Find Nodes?
    Voting Booth?
    It has been suggested to rename Perl 6 in order to boost its marketing potential. Which name would you prefer?

    Results (468 votes). Check out past polls.