in reply to Re: Perl documentation
in thread Perl documentation

What we perhaps need to do is to direct people towards perltoc instead of the relevant doc itself if it's obvious where to look after reading perltoc.

ihb

Read argumentation in its context!

Replies are listed 'Best First'.
Re^3: Perl documentation
by PodMaster (Abbot) on Aug 13, 2004 at 01:12 UTC
    What? That's just stupid. Why would Pod::Master be mentioned in perltoc? Why would you say look at the index instead of perlref or perlre?

    MJD says "you can't just make shit up and expect the computer to know what you mean, retardo!"
    I run a Win32 PPM repository for perl 5.6.x and 5.8.x -- I take requests (README).
    ** The third rule of perl club is a statement of fact: pod is sexy.

      Please read my reply again. But I'll help you out:

      ihb: ... if it's obvious where to look after reading perltoc

      This is the key sentence and answers both your questions.

      Why would Pod::Master be mentioned in perltoc?

      I never said it should. Read my quote above.

      Why would you say look at the index instead of perlref or perlre?

      Because they obviously didn't read perltoc (read my quote again) and the next time they want to know about a perl feature they'll come asking where to look instead of looking it up themselves in perltoc.

      We point people towards perlfunc when it's a question about functions. We point people towards perlref when it's a question about references. We should perhaps point people to perltoc when it's a question about documentation.

      You say that perltoc "looks fairly well organized and indexed to me." Problem is, few know to look there.

      ihb

      Read argumentation in its context!

        Because they obviously didn't read perltoc (read my quote again) and the next time they want to know about a perl feature they'll come asking where to look instead of looking it up themselves in perltoc
        Teaching users that perltoc exists is good. Substituting perltoc for perlref (or a particular section of it) is bad. Its like telling users "learn How to RTFM, the answer is in the docs". Its best to point out exactly where the answer lies.

        MJD says "you can't just make shit up and expect the computer to know what you mean, retardo!"
        I run a Win32 PPM repository for perl 5.6.x and 5.8.x -- I take requests (README).
        ** The third rule of perl club is a statement of fact: pod is sexy.