On Fri, Jul 2, 2010 at 10:33, Gabor Szabo <szab...@gmail.com> wrote:
> 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
>
This is mostly handled by perlfaq/perldoc -q QUESTION today. Long
term projects I am considering include a rosetta stone for
ruby/python/? and a cookbook (but this is already what the FAQs are to
a certain extent, si I need to think more about that).
--
Chas. Owens
wonkden.net
The most important skill a programmer can have is the ability to read.
