Message from discussion perl6-lang Project Management
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>
X-Mailer: Apple Mail (2.546)
X-SMTPD: qpsmtpd/0.12, http://develooper.com/code/qpsmtpd/
From: mlazz...@cognitivity.com (Michael Lazzaro)
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.
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
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
> So either we have the definitive docs that define all the details of
> 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.