Re: RTFM works perlfectly. (Re: Re: Re: Re: Debian removed perlreftut)

[sauoq]

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.";

[Juerd]

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' }