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. (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. :-) Some tentative thoughts: Probably need a very fine-grained tree structure; short pages, lots of them, crosslinked. Everyone seems to like the "booklike" style better than the "recipe" style, but wants the pages to be short, focusing on one topic at a time. Existing Perl5 documentation is extremely well written, but exists in quite large, sometimes hard-to-digest chunks. Not very easy to find where a given sub-topic is discussed. Must be distributable in POD, manpage, pretty-printable, and online forms. Moderated, annotated pages (like the POOC recipes) may be useful for focusing detailed feedback on each page, without introducing the problems of choppy style and "battling rewrites" inherent in wiki-based pages. The booklike style, but broken out into small pages with individual notations. Seems like it should be possible to be both detailed and beginner-friendly, if concepts are introduced in a well-organized fashion. Likewise, it seems probable that test cases could be organized to exactly mirror documentation sections or pages. If both sections and tests are written and edited together (long-term), a great opportunity to make sure the docs always match the tests, and vice versa. Conversations on this mailing list are going to look a lot like perl6-language, except more aggressively focused on one narrow area at a time. Starting from data types & behaviors, moving on to operators, then blocks, conditionals, etc, then regexen. 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. Comments? MikeL
