Think "Language Reference" (was Re: Initial notes)

>> I also think that we shouldn't try to provide too exact and final
>> documentation at once. Just define each area "with enough detail"
>> (whatever that means) and then move on. Until whole language-design
>> is somewhat complete, there will be things which requires earlier
>> decisions to be changed.

Let me explain what I (personally) am hoping for.  I don't think we 
should be locking down every aspect of the language before moving on, 
because we clearly can't.  But just as clearly, if we document portions 
of the language without going into all the details, we aren't really 
accomplishing anything: we haven't found potential buried issues, we 
haven't documented it well enough to answer user questions, and we 
haven't given p6i anything useful to work with.

In other words, if we leave the detail out of a section, we're going to 
have to write the section over again anyway, and there's no point.

So what I'm after is *lots* of detail, but in very narrow doses; hence 
a strict tree of sections and subsections.  We've had some initial 
proposals with outlines & contents for section 1; in general, however, 
I think we are still thinking _much_ too broadly.

***** For this phase, think Big Language Reference, _not_ Little 
Language Summary.  Or think along the lines of the Perl5 Cookbook, in 
which very small areas of the language are explored with impressive 
detail before moving on to the next small area.

For example:  we know Perl6 will have num, int, bit, and str types, or, 
loosely translated, "numbers" and "strings".  From that, we now must 
nail down the exact behavior of those types in every useful situation.  
There should be a section on "Numeric Types & Values", that contains or 
links to _all_ information about how Perl6 deals with numerics.  A user 
should be able to find out everything they need to know about how the 
numeric types from that one section, and not have to search anywhere 
else.

After we've nailed down the behavior of all the primitive builtins, 
then we can get to arrays, then hashes, then statements & operators, 
then blocks/closures/subroutines, etc.  A depth-first effort.  (I'll 
post another note giving an example of what I mean.)

As much as we've said Perl6 needs docs that will be understandable to 
beginners, this _initial_ part of the process will not directly 
accomplish that.  That will be phase 2, after we have the "reference" 
material from which to write the beginner version.  Hopefully, however, 
we will be able to write the reference material with the proper 
ordering & structure to be useful even to beginners, because everything 
will be easy-to-find in the tree -- beginners might just not want to 
drill down as far.

In general, I want us to be fairly easygoing about issues like POD 
formats, HTML look & feel, etc.  A rough consensus, but not set in 
stone, which is why I've been trying to close those things out as 
rapidly as possible.  On the text of the documentation itself, I think 
we need to be real hardnoses, and ask all the tough questions.

MikeL