Newsgroups: perl.perl6.language
Path: archiver1.google.com!news1.google.com!newsfeed.stanford.edu!nntp.perl.org
Return-Path: <mlazz...@cognitivity.com>
Mailing-List: contact perl6-language-h...@perl.org; run by ezmlm
Delivered-To: mailing list perl6-langu...@perl.org
Date: Wed, 6 Nov 2002 12:51:28 -0800
Subject: Re: perl6-lang Project Management
Content-Type: text/plain; charset=US-ASCII; format=flowed
Mime-Version: 1.0 (Apple Message framework v546)
Cc: "'af...@corp.vlex.com'" <af...@corp.vlex.com>,   Allison Randal <a...@shadowed.net>, perl6-langu...@perl.org
To: Garrett Goebel <garr...@scriptpro.com>
In-Reply-To: <71BEC0D4E1DED3118F7A009027B12028010BE5FA@EXCH_MISSION>
Message-ID: <8546CB84-F1C9-11D6-AC10-00050245244A@cognitivity.com>
Content-Transfer-Encoding: 7bit
X-Mailer: Apple Mail (2.546)
X-SMTPD: qpsmtpd/0.12, http://develooper.com/code/qpsmtpd/
Approved: n...@nntp.perl.org
From: mlazz...@cognitivity.com (Michael Lazzaro)
References: <71BEC0D4E1DED3118F7A009027B12028010BE5FA@EXCH_MISSION>
Lines: 53


On Wednesday, November 6, 2002, at 12:26  PM, Garrett Goebel wrote:
> Angel Faus wrote:
>> So, while we all wait for Larry to wait the design, is there any
>> reason not to start working in the documentation?

Yes!  Someone gets it!  The Apocalypses and Exegesis are not "formal" 
documentation, they're the initial, informal specs.  The finished 
documentation won't look anything like them, right?

> Any chance of getting a wiki setup at:

My problem with a wiki approach is that it tends to lead to lots of 
duplication of effort, with some sections entirely ignored, as well as 
a wide range of writing styles.  I think a better approach is, indeed, 
for the community to help with documentation, but to do so in a more 
structured way.  This is why I prefer a mailing list approach, with 
questions & answers posted, then documented, in a particular, fairly 
rigid order, where everyone is concentrating on the same excruciating 
details at once, then boom, it's done, move on.  Right now we have the 
mailing list, but not the structure.

Two notes:

1) The primary need right now is not documentation in itself, but the 
community process of *writing* the documentation.  It is by 
methodically *finding* the holes in the specification that the 
specification will finally becomes complete enough to implement 
accurately.

2) Anyone involved in a community documentation effort must agree that 
ALL of it is open source or public domain, and _specifically_ that any 
members of the community who will be writing treeware (books) may use 
any of that text in their own efforts.  This is a dealbreaker, for me: 
I have zero desire to squish commercial documentation efforts -- I 
think those people deserve 100% of that income.

On Wednesday, November 6, 2002, at 12:26  PM, Nicholas Clark wrote:
> I see no reason why this doesn't also apply to specs vs regression 
> tests.
> So either we have the definitive docs that define all the details of 
> the
> language, or we have the regression tests that define all the details.

I confess I have worked that way myself, on some projects, but I fear 
we aren't capable of that yet.  We still need to flesh out the 
"english" explanations of co-routines, superpositions, and other 
advanced features.  I would rather define how it worked, and test to 
that, then test how it worked, and write up the english implications as 
we accidentally discover them.

MikeL