On Fri, Jul 2, 2010 at 3:57 PM, David Golden <xda...@gmail.com> wrote:
> On Fri, Jul 2, 2010 at 8:22 AM, Chas. Owens <chas.ow...@gmail.com> wrote:
>> It isn't just that say wasn't added until 5.10, it is that say doesn't
>> even work without a "use 5.010;" or similar statement. This means
>> that the person coming to the Perl for the first time will encounter
>> one of three scenarios:
>
> You're missing my point, or I'm not being sufficiently clear.
>
> The vast majority of the time, the documentation is being read by
> people who are *NOT* "coming to Perl for the first time" and thus I
> don't think that *all* documentation should be written for the
> absolute beginner.
>
> Intro-level documentation ("intro", "tutorial", "quick start",
> possibly "faq") should. Reference documentation should not. IMO,
> that includes things that would come from perldoc -f, etc.
>
> Yes, we want to make Perl easier to learn for the novice, but not at
> the cost of bloating the documentation for the average user.
Interestingly I would have said that the documentation is mostly needed
by novices or by people who rarely use Perl. The difference might be
because I encounter so many people who are learning Perl.
What they usually would need, IMHO is an easy way to grab an example
of simple task.
"How can I open a file?"
or even
"How can I read from file?"
There are also many people familiar with other languages and they are looking
for solutions based on their language:
"How can I trim white spaces?"
or
"What is the equivalent of the 'trim' function?"
Then there are the people who inherit a piece of code without any
background in Perl.
They would need to get answer to the questions "What is this $_ ?",
"What is $_[0] ?" or
"What is ||= ?".
I don't know much about experts but I think we should make it easy for
people with no,
or little background in Perl to get simple answers to their questions
with pointers to
further details. I think the vast majority of people using Perl are in
this category.
Gabor
