Re: Initial notes

Michael Lazzaro wrote:

>"Joseph F. Ryan" wrote:
>  
>
>>Angel Faus wrote:
>>    
>>
>>>I think that the best way would be to create an schema of a language manual,
>>>and fill the documents as we proceed reviewing the Apocalypses.
>>>      
>>>
>
>
>Agreed -- we should certainly figure out the overall structure first,
>before doing much else.  I think that's a pretty good start for an
>outline, too.
>
>Now given our intended goal of it being detailed enough for internals,
>but written even for beginners, how do we "package" the materials? 
>(Should it be a concise language reference, a series of tutorials, a
>formal or informal booklike document that explains everything in detail?
>  I know, I know, everyone's going to say "yes, all of them, and it
>should dispense softdrinks from your CD-ROM drive upon request...")
>

I think the biggest concern should be converts from perl 5.  Most people 
will
have an attitude similar to: "I know how to do X in perl5, now how do I do
that in perl6?" I think that a set of tutorials (that refer to the main docs
many, many times) that show how to translate common idioms, structures, and
techniques from perl 5 to perl 6, such that if a person reads through them,
they'll at least have enough knowledge on perl6 to begin to write in it, and
know where to turn to when they have problems.

<snip>

>After users gain some experience, the role of the online/manpage
>documentation shifts to one of "support".  People will go to the docs if
>any of these is true:
>
>-- they have a very specific question
>-- they have a very advanced question
>-- they have a question their book(s) don't answer
>-- they don't know enough about their question to know where to look for
>it in the book.
>
I think that most people first go to a "support place", i.e. PerlMonks, 
Perlguru, #perl, c.l.p.m, etc., where
the people there will refer them to the correct docs.

Joseph F. Ryan
[email protected]