|
in reply to Re: Re: Re: Debian removed perlreftut
in thread Debian removed perlreftut
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's dual meanings. Was: RTFM works perlfectly. (Re: Re: Re: Re: Debian removed perlreftut)
by scrottie (Scribe) on Aug 14, 2003 at 17:38 UTC
|
"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 | [reply] |
Re: RTFM works perlfectly. (Re: Re: Re: Re: Debian removed perlreftut)
by sauoq (Abbot) on Aug 14, 2003 at 17:36 UTC
|
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.";
| [reply] |
|
|
what was wrong with diotalevi's suggestion that you point them to perlreftut on perldoc.com?
I never said anything was *wrong* with the suggestion.
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
The pointer without the personalized help works well. Feel free to ask our visitors what they think of #perlhelp. They tell us they like how we tell them to RTFM in a friendly way.
Juerd
# { site => 'juerd.nl', plp_site => 'plp.juerd.nl', do_not_use => 'spamtrap' }
| [reply] |
|
|
