Re: Initial notes

[Richard Nuttall]

Michael Lazzaro wrote:

Here's some notes based on the first bits of feedback -- something to
throw rocks at, as it were.


"The overall project goal is to produce documentation that will:"

(1) define precise semantics for the Perl6 language; discover and
document ambiguous possible behaviors and report them to the design team
(Allison, Dan, Damian, Larry) for review and decisions.

(2) provide detailed test cases allowing Perl6 implementors and the QA
team to verify functionality as it is written.

(3) encourage community interest and participation in Perl6, growing the
community and the manpower available to implement the language.

I think we need to allow some sections to be the definitive documentation, and
others to be 'user-contributed' and rather looser later on in the project, possibly
with some of the examples getting pulled in to the formal docs if appropriate.

(4) be distributed, when complete, as the user documentation for Perl 6.0.

Note that we have things here with quite divergent intended audiences. Not saying that's a problem, just pointing it out. :-)

How (if at all) does this project link into the internal documentation of the coding team ?
It would be nice to be consistent, and allow the links to work across that boundary
if possible. Maybe a well developed system would encourage the coders to add more
comments into the code than they do currently.

[...]

Should start small. No tutorials until docs & tests are done. No
working on A3 until A2 behaviors are *locked*, to whatever extent that
proves possible.

I agree strongly on the focus, but presumably the mechanism to manage the above
pages, etc. will be done early on ?

R.

--
Richard Nuttall