Beefy Boxes and Bandwidth Generously Provided by pair Networks
Pathologically Eclectic Rubbish Lister

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]
[marto]: anyway, don't come to Glasgow for the football :)
[holli]: the hell? i have a scriptblocker on.
[holli]: how do you update a different window without javascript?
[holli]: ah, chatterbox right
[marto]: it's a normal HTML form, with some hidden input fields
[holli]: forgot that thing exists for a moment.
LanX welcome to the twilight zone ...
[Eily]: LanX well since the onion is your eye you should see it everywhere
[marto]: sounds eye watering
[LanX]: oh your talking about my pic?

How do I use this? | Other CB clients
Other Users?
Others studying the Monastery: (12)
As of 2017-12-14 16:18 GMT
Find Nodes?
    Voting Booth?
    What programming language do you hate the most?

    Results (398 votes). Check out past polls.