Beefy Boxes and Bandwidth Generously Provided by pair Networks
XP is just a number
 
PerlMonks  

Re: Re: Debian removed perlreftut

by Juerd (Abbot)
on Aug 14, 2003 at 11:46 UTC ( [id://283837]=note: print w/replies, xml ) Need Help??


in reply to Re: Debian removed perlreftut
in thread Debian removed perlreftut

So, big deal.

It means helping people in #perlhelp need to un-learn telling people to "perldoc perlreftut". About helpful but unnecessary documents: there should be more of those.

Juerd # { site => 'juerd.nl', plp_site => 'plp.juerd.nl', do_not_use => 'spamtrap' }

Replies are listed 'Best First'.
Re: Re: Re: Debian removed perlreftut
by diotalevi (Canon) on Aug 14, 2003 at 11:55 UTC

    No, it means re-learning to say `perlreftut on perldoc.com`.

      That means either a special case for perlreftut, or changing the default resource to perldoc.com. I like that perldocs are available locally, come with perl and don't need a web browser to be read. I also like saying "perldoc perllol; perldoc perlreftut; perldoc perlre" when someone asks how to get a 2D array in Perl.

      Juerd # { site => 'juerd.nl', plp_site => 'plp.juerd.nl', do_not_use => 'spamtrap' }

Re: Re: Re: Debian removed perlreftut
by sauoq (Abbot) on Aug 14, 2003 at 14:29 UTC
    It means helping people in #perlhelp need to un-learn telling people to "perldoc perlreftut".

    So? Big deal.

    Point them to perlref, perldsc, and/or perllol. Or, as diotalevi said, point them to perldoc.com. Or give them the ten minute tutorial (with examples) that it usually takes to explain references adequately on IRC. What's the point of "helping" people if all you do is cite perldoc perl all the time.

    In any case, it is far better for us to have to unlearn perldoc perlreftut than for Debian to violate the overly restrictive copyright on a single document in the Perl distribution. Better to remove the offending document than to remove perl itself. Afterall, perlreftut is useless when it comes to running scripts.

    -sauoq
    "My two cents aren't worth a dime.";
    

      Or give them the ten minute tutorial (with examples) that it usually takes to explain references adequately on IRC.

      We do that only if they don't understand the documentation. And no, it does not take ten minutes. It would take ten minutes to teach it to intelligent people; but they don't need explanation because they understand the documentation. In practice, when someone doesn't understand the documentation, it takes up to one or two hours before they understand how references work.

      What's the point of "helping" people if all you do is cite perldoc perl all the time.

      Perldocs are a maze to most people. It is hard to find out that you need too look for "references" to get what you think is called "a two-dimensional array". It's hard to look up the flip-flop operator if you don't know that it is called an operator. Finding information about tr is hard if you think the answer can be in perlre. It's hard to read FAQs if you don't know they exist.

      You know where and how to find documentation. I managed on my own too. But many people need a push in the right direction. Often, they don't mind reading documentation but they simply don't know which documents are good for them.

      So this is how we help people on #perlhelp. We tell them to RTFM, and specify which manual. Depending on the situation, this can be a perldoc, Coping with Scoping, Suffering from Buffering, Beginning Perl, a module's POD, one of the many PM Tutorials, etcetera, etcetera.

      Our strategy works. We don't just try to help, we actually help these people. And once in a while (3..5 times per day) someone needs more help than RTFM. Because we tell the others to RTFM, we have enough time to help the people who really need it.

      The point of helping people if all we do is cite "perldoc $document" all the time is helping people.

      In any case, it is far better for us to have to unlearn perldoc perlreftut than for Debian to violate the overly restrictive copyright on a single document in the Perl distribution. Better to remove the offending document than to remove perl itself. Afterall, perlreftut is useless when it comes to running scripts.

      I agree that it is better to remove perlreftut than perl. I also agree that Debian did what it thought it had to do. I don't like what they had to do, though. It still is Debian's fault, though. Even though they cannot ship perlreftut, that's still because of *their* decisions.

      I think the best solution would be to re-license perlreftut if that is possible. I think that'll happen eventually. In the meantime, people will be disappointed when they notice that this document is not installed on their computers.

      Juerd # { site => 'juerd.nl', plp_site => 'plp.juerd.nl', do_not_use => 'spamtrap' }

        "RTFM" can expound the virtues of a particularly fantastic manual, or it can express the frustration of having to direct someone to the manual in the first place. The ambiguity introduced by the accronym is kind of fun - you can suggest both at the same time to a degree.

        RTFM is fun, but most often, an explicit version of it is used. I've often told novices "There is a really good tutorial on that at XXX. Read through that and let me know what problem you run into next, it is probably something simple". I've also told a great number of novices "I told you to do XXX. You didn't do it. You keep asking the same question. You're ignoring my answers. Don't come back until you've atleast tried XXX or you get a new question." Sometimes, I'm more rude than that. Far more rude.

        Juerd defended the use of RTFM in the polite sense. I'd like to defend the use of RTFM in the nasty sense. Both are valid.

        Juerd mentioned IRC. #perlhelp is a great chance to help people. People come in there without any direction other than they've decided to use Perl, and it is a great chance to be a positive influence - encourage them, point them at resources, empathise with them in their learning process, and let them blow off some steam as they talk about what they're trying to do. When you listen to them, often they give you some ear time, too, and you can expouse the virtues of CPAN and the documentation and good style. It is usually a good, healthy, process.

        Sometimes it isn't. Sometimes someone with a really 1337 name wanders in, uses wretched grammar, complains that something doesn't work (presumably they mean for them on their system), abbreviates everything, asks questions without question marks, and uses cut and paste to resend their "question" to the channel over and over. This isn't a razor, but a stereotype. Sometimes this isn't a positive indication, but 9 time out of 10 giving a helpful reply to one of these individuals incites them into a rage. Saying, "Your variable is losing it's value at some point. The best thing to do is indent your code, get rid of the globals and pass data using the function call syntax like this", provide an example, and suggest that the problem will likely go away on it's own if they do that, but if it doesn't, you'll look at it, makes them mad. Really mad.

        Being reasonable ourselves, we like to assume that other people are reasonable, and that this "novice" is merely trying to solve a problem and is perhaps a bit frustrated. These people aren't novices; they're well versed in conning people into doing things for them through feighted anger and summoned hostility. Their refusal to do even simple things themselves when lead by the hand forces people to either do it for them or get locked into a bitter battel. They don't not learn things because it is too hard to, but because it is easier to scream and cry. They might be kids, but I've known plenty of adults to conduct themselves in this manner.

        Saying "RTFM", even where the nasty "F" is implied, communicates that you aren't willing to do the task for them if they don't consider it worth doing themselves. It communicates that they have everything they need at their disposal to do it, but it isn't your problem, and they can't make it your problem.

        Using "RTFM" in the ambigious sense communicates that you're willing to help, give pointers, even ensure that good, correct documentation is available if it isn't already, but the person seeking help should politely respect that isn't your problem, and should procede with the understanding that you're willingly sacrificing somne time even though you don't have to. No, this isn't a concious understanding, but the unconcious mechanism works very well. It is the same cool, short, but well meaning help you'll get if you ask for directions in New York. "I don't know you, I'm not going to go out of my way for you, but I mean you well, and I hope this helps".

        Juerd hit the nail on the head. Avoiding the pathological cases let you focus not only on your own work so that you can keep that IRC channel open, but it also lets you give attention to people that actually do need help still after they've read the documentation or followed your initial bit of advice about indenting their code or using some module.

        Reguards,
        -scott

        This is the important part of this discussion, so I'll put it first:

        It still is Debian's fault, though.

        I very much disagree. As I said, I believe the offending document should be removed from the Perl distribution pending a license change. If it isn't distributed with exactly the same terms as Perl itself, it shouldn't be distributed with Perl at all. It isn't reasonable to expect every user to inspect every file in the distribution for different licensing terms.

        The rest isn't really important but deserves response...

        In practice, when someone doesn't understand the documentation, it takes up to one or two hours before they understand how references work.

        Not in my substantial experience. I used to op on #perl on openprojects.net starting when there were about 10 people in the channel and continuing until it grew to about 75 regularly. (In fact, that's how I "met" Brendan a.k.a. bod.) I've helped many people get a grasp on references in less than 20 minutes.

        We tell them to RTFM, and specify which manual. Depending on the situation, this can be a perldoc, Coping with Scoping, Suffering from Buffering, Beginning Perl, a module's POD, one of the many PM Tutorials, etcetera, etcetera.

        You mention several documents that are not part of the perl distribution... so, tell me again... what was wrong with diotalevi's suggestion that you point them to perlreftut on perldoc.com?

        I agree that the perl documentation is a maze and that pointing them at the right one can be helpful, however, some personalized help and a pointer to the right TFM to R is almost always more helpful and it leaves a better impression too.

        -sauoq
        "My two cents aren't worth a dime.";
        

Log In?
Username:
Password:

What's my password?
Create A New User
Domain Nodelet?
Node Status?
node history
Node Type: note [id://283837]
help
Chatterbox?
and the web crawler heard nothing...

How do I use this?Last hourOther CB clients
Other Users?
Others admiring the Monastery: (4)
As of 2024-06-20 02:26 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    No recent polls found

    Notices?
    erzuuli‥ 🛈The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.