perl6-lang Project Management
Michael Lazzaro
The A's and E's represent the framework and major decisions for Perl6,
but not every minor niggling issue and detail. As we keep seeing,
there is no shortage of things to pin down. We need to do that, and we
need to do it in the same rough order as the Apocalypses, and we need
to do it _NOW_.
Larry and the rest of the design team are the ones leading the Perl6
language design. I hope, however, that they do not represent the sum
total of the useful labor that can be applied to this process. The A's
and E's, by themselves, are not sufficient documentation to fully guide
the full implementation of the language, and I would surely hope that
we're not intending to wait until Apocalypse 33 is completed before
fully documenting the implications of Apocalypse 2. Rather than
placing it at the feet of the design team to do in their
no-doubt-voluminous spare time, I would expect that we could be helping
more directly.
For the amount of discussion generated on this list, our overall
contribution to the effort is less than it should be. Primarily
because we're Discussing, and not Planning. It's great that we can ask
questions, and get them answered, but who cares, when the next person
has to ask the same $#@%$ thing?
The entire reason I'm writing those pages and pages of primitive docs
is to thoroughly get into all the nooks and crannies of the language,
and make sure every stick of it is as
complete/simple/regular/obvious/intuitive as humanly possible. And to
make sure that, somewhere, We Have It Written Down. But if you look at
the pseudo-chapter I just posted -- which covers only a tiny fraction
of Apocalypse 2 -- you will still see holes where rudimentary behaviors
are, as of yet, unclear.
My proposal is this:
Let us (perl6-lang, with the help of Larry/Damian/etc) focus on
fleshing out every last detail implied by Apocs 2-N, _in that order_.
Let's not worry about the block constructs until we've got nearly all
aspects of the operators down. Let's not worry about the operators
until we've gotten the behavior of numeric, string, array, hash, etc.
values and variables down. Yes, the ordering can never be exact
because it's all interrelated. But we can accomplish _something_
towards the detailed, drop-dead accurate definition of all aspects of
Perl6. Project Rule #1: IF IT ISN'T DOCUMENTED, IT ISN'T DONE.
If we can impose enough self-management to accomplish it, I am willing
to help in the excruciating task of Writing Things Down, and in the
even worse task of helping focus the process. But I can't, without
help -- specifically, the willingness of the community to focus on
individual areas one-by-one, so that we can close them out. There's
just no way I can document anything right now -- we haven't made enough
decisions to document.
So what say you? Can we migrate perl6-language into a list that
finalizes aspects of the design, documents them, and revises them as
needed, rather than our usual circular discussions of things already
long-since past?
MikeL
Allison Randal
let you in on some of it. Let's start with a step back into a bit of
history:
We started off with an intense RFC process. This produced many good
ideas, not-so-good ideas, and ideas with potential but desperately
needing polish. If you'd like a recap, you might try MJD's article on
the subject (http://www.perl.com/lpt/a/2000/11/perl6rfc.html). One of
the major things that was lacking from the RFC process was focus. The
advantage of community contribution is that it brings out good ideas
from many different perspectives. The disadvantage is that the ideas
form no coherent whole. Larry was the obvious choice to provide the
needed focus.
The second phase (the one we're in now), is for Larry to take the RFC's
and produce a coherent design. The original expectation was that this
would take 2 weeks. Looking back, that seems ludicrous. We now know what
an intense amount of work is involved in each feature. Hey, we live and
learn. :)
Even though this review process is taking longer than expected, this is
the right way to proceed. Just look at the first 5 Apocalypses. Larry
has taken us in directions that no one expected and the results are
worth getting excited about.
But, here's the deal. When you place the weight of producing a coherent
design on one person's shoulders, you're limited by the amount of work
one person can do. So what we don't need right now is another slew of
RFC's (or their equivalent) for Larry to review. That isn't to say that
we can't or won't discuss issues that come up from earlier Apocalypses.
We will and we should. But that isn't the focus. It can't be. If we
spend all our time fleshing out the details of earlier Apocalypses,
we'll never finish. Hmmm... let me rephrase that. If we spend all
Larry's time fleshing out the details of earlier Apocalypses, Larry will
never finish.
This is in no way intended to dampen your enthusiasm. It is welcomed.
But please keep it in perspective.
The project is proceeding in a much more orderly fashion than you might
think if p6-lang is your only exposure. Apocalypse 6 will be coming out
soon, though slightly delayed by the recent furor over operator shifts.
If you really want to be involved where the rubber meets the road --
where the "abstract" design gets tested and every last detail must be
fleshed out -- you might contribute to Parrot. It has a good many of the
features of the first 5 Apocalypses implemented already.
Allison
Michael Lazzaro
On Tuesday, November 5, 2002, at 11:18 PM, Allison Randal wrote:
> Since you're interested in the management of the Perl 6 project, I'll
> let you in on some of it. Let's start with a step back into a bit of
> history:
OK, let me pause for a second... pause, pause, pause... OK, I'm better
now. Please forgive me, I'm going to be quite forceful in my
evaluation of the situation here. To the point of making a Simon C.
post look mellow. Get ready for some spectacular virtual
coffee-mug-throwing here.
This is a good summary, but please note that I'm already painfully
aware of the RFC process and phase 2, and have followed it religiously
since the beginning, though I have been purposefully invisible through
most of it. Indeed, it was the RFP process which caused me to decide
that my company could no longer continue to base our commercial
software on Perl: with a few noteworthy exceptions, the RFCs all
focused on narrow "feature add-ons" that did precious little to solve
the core issues that have served to limit Perl5 in the marketplace.
It is the high quality of Parrot that later convinced me to hesitate in
my decision, but it is Apoc5 that later convinced me to reverse it, and
to even get directly involved. Apoc5 convinced me that, indeed, Larry
and the design team were reworking the base assumptions of the language
in a truly innovative way, and that the result was going to be what the
real-world business community was hoping for.
> We will and we should. But that isn't the focus. It can't be. If we
> spend all our time fleshing out the details of earlier Apocalypses,
> we'll never finish. Hmmm... let me rephrase that. If we spend all
> Larry's time fleshing out the details of earlier Apocalypses, Larry
> will
> never finish.
This, then is my point. I am not saying that Perl6 does not have a
management strategy for dealing with this. I am saying that the
management strategy for this particular part of the effort is so
incredibly piss-poor as to be nonexistent. Parrot Good. Larry Good.
Big, Big HOLE in the middle. _Who_ is fleshing out the mindless,
trivial details that Larry posts to this list, and _who_ is
creating/updating the documentation to reflect those changes? Anyone?
If someone is, what, is it supposed to be a secret? Or does it simply
not exist, and Why The Hell Not?
> The project is proceeding in a much more orderly fashion than you might
> think if p6-lang is your only exposure.
But what other exposure would I have? No, seriously -- let me
summarize Perl6 from the standpoint of someone who isn't in the loop,
whatever the "loop" is, so the people who _are_ in the loop can tell me
why I'm completely misinterpreting the obvious public faces of the
effort:
-- Apocalpyse 2 came out May 3rd, 2001. That's, what, about 18 months
ago. Since then, there has been no edits or revisions: none of the
obselete references have been purged or annotated, and none of the
profound new decisions that have been made since then have been
acknowledged. Ditto for Apoc 3 (Oct 2001), Apoc 4 (Jan 2002), and Apoc
5 (June 2002). Basic, fundamental decisions have been *invalidated*,
but you will only know this if you have read and perfectly remember
every post to perl6-lang since inception. Great, just great.
-- The Apos and Exes continue to be the _ONLY_ meaningful source of
documentation of previously decided behaviors. No member of the
community besides Larry and Damian has contributed in an ongoing way to
documenting the rudimentary behavior of Perl6. Questions asked on
perl6-language continue to be asked, repeatedly. Explanations are
given, repeatedly, often contradicting previous explanations. Aside
from Piers and his stunt doubles, explanations result in no "findable"
specifications whatsoever.
-- Basic, fundamental questions like what each of these lines do:
my int $n = 5; # OK
my int $n = 5.005; # trunc or err?
my int $n = "5.05ff" # 5, 0, undef, Nan, or exception?
my int $n = "fdsjfdf" # 0, undef, Nan, or exception?
... are being asked repeatedly of _me_, implying that either (1)
nobody knows, (2) some people know, but they aren't telling, (3) people
know, and it has been answered, but people can't find the answer
anymore because it's lost in N other unrelated answers, or (4) people
no longer trust the answer, because they don't know what other
decisions the answer was originally predicated on.
-- The "latest news" on the Perl6 section of dev.perl.org was updated
July 7th, introducing Piers, and other than linking to Piers' summaries
contains no information pertinent to Perl6 -- only Parrot.
-- It's November, 2002. We have just been through a hellacious thread
reworking operators. (Apoc 3) The only documentation of those
decisions has been my continual reposting of the current status, which
I had to practically _force_ down people's throats.
I don't *WANT* to write damn documentation. I wrote a first-chapter
summary of some basic Apocalypse 2 stuff because, a year and a half
after it first came out, NOBODY HAD DAMN WELL DONE IT YET. Worse, I'm
bloody *volunteering* great gobs of time to do it, and it's like
pulling teeth to get people to agree to it!
So, to review: if this was the behavior of my staff, I'd fire them. If
my staff said "well, we're waiting for Timmy to finish the design, then
the rest of us can start helping too", I'd fire all of them but Timmy.
And I'd feel damn good about doing it.
If there are efforts going on behind the scenes to document the
current, as-it-stands-at-this-moment Perl6 design, to revise the Apocs
and Exes, to write online documentation, etc, than I strongly object to
keeping that information private. If there _IS_ no effort to do this,
under the assumption that Larry/Damian will get around to it in a year
or two, after we get to Apocalpyse 15, or 27, or 33, then Good Lord, I
have no rational response to that.
> If you really want to be involved where the rubber meets the road --
> where the "abstract" design gets tested and every last detail must be
> fleshed out -- you might contribute to Parrot. It has a good many of
> the
> features of the first 5 Apocalypses implemented already.
I would *love* to. What should I work on first, simple numerics and
string behaviors? Oh, right -- I can't, the details aren't final. OK,
what about blocks and flow control? Nope, because some things in Apo4
are changing in as-of-yet unspecified ways. Oh, I know! I help build
the core type system -- all the Perl6 primitive types. Damn, no I
can't -- the only even remotely complete list of primitive types that
exists is the one I posted to this list a week or two ago. And I still
don't even know if "num" and "int" inherit from an abstract base class
that we still have to come up with a name for (in order to even be able
to test for its context) or if "int" is supposed to be a kludged
subclass of "num", or what.
When I first posted the incredibly sparse-of-solutions POOC, it got,
what, 650+ unique individuals in the first 7-10 days? The only place
it was even mentioned was on this list, and the weekly summary of this
list. That implies there are a substantial number of people who are so
eager to learn about Perl6 that they're willing to wade through
non-existent, vaporous specs to find out. Maybe we could somehow
harness that energy in a productive fashion?
Again, my point is that Parrot is doing fine, and Larry is doing fine.
But the hole in the middle -- coming up with the details so that the
Parroteers can actually implement something, and not have to sit on
their @$$es for a few months after they've finished the non-Perl core
-- is getting _very_ _wide_.
What do I have to do? Throw mugs? This isn't a damn social club. If
people don't want me to write some documentation, FINE. Show me what
you've got. Post it, and I'll shut the hell up. But don't tell me we
don't need it yet, because not a day goes by when someone on
perl6-language proves that we _do_ need it, and are suffering greatly
without it, and that Larry and Damian are wasting untold hours because
of it.
MikeL
Simon Cozens
> Big, Big HOLE in the middle. _Who_ is fleshing out the mindless,
> trivial details that Larry posts to this list, and _who_ is
> creating/updating the documentation to reflect those changes? Anyone?
Allison is, but she was too modest to say so. (And I fear, too busy
to check in much in the recent past. :( )
It's all at http://cvs.perl.org/cvsweb/perl6/doc/design/
--
Ermine? NO thanks. I take MINE black.
- Henry Braun is Oxford Zippy
Jonathan Scott Duff
> So what say you? Can we migrate perl6-language into a list that
> finalizes aspects of the design, documents them, and revises them as
> needed, rather than our usual circular discussions of things already
> long-since past?
What would be useful would be a big map of all that is or might be
perl 6. Items that are still in flux could be marked as such and have
pointers to the relevant mail thread(s). Items that are finalized
could have links to the documentation that describes those items.
As for who updates the map of the onion and its associated
documentation, I don't know. It should be a small group of people
(perhaps only one) though. Right now, I guess it's just Allison.
-Scott
--
Jonathan Scott Duff
du...@cbi.tamucc.edu
Chromatic
> If you really want to be involved where the rubber meets the road -- where the
> "abstract" design gets tested and every last detail must be fleshed out -- you
> might contribute to Parrot. It has a good many of the features of the first 5
> Apocalypses implemented already.
One excellent opportunity is to write tests for Perl 6 features. Testing gives
several benefits:
- exploring the syntax with a working interpreter
- mapping the boundaries of what's expected
- providing good feedback for debugging Perl 6
- exposing what's not yet implemented
- ensuring that regressions only happen once
I'd be thrilled to help anyone learn how to do this. It's one of the most
important places to contribute, but it's all-too-often overlooked.
-- c
Allison Randal
> mlaz...@cognitivity.com (Michael Lazzaro) writes:
> > Big, Big HOLE in the middle. _Who_ is fleshing out the mindless,
> > trivial details that Larry posts to this list, and _who_ is
> > creating/updating the documentation to reflect those changes? Anyone?
>
> Allison is, but she was too modest to say so. (And I fear, too busy
> to check in much in the recent past. :( )
>
> It's all at http://cvs.perl.org/cvsweb/perl6/doc/design/
The updates to A1 are finished and pending approval. A2's updates are
half finished. The rest of the revisions to the Apocalypses and Exegeses
are in the form of extensive notes.
Feel free to send me documentation patches (follow Parrot's format:
http://www.parrotcode.org/patchfaq). They'll be accepted if they're
clearly written, technically correct and relevant. They'll be subject to
my edits and a review process by the entire design team. And keep in
mind that I've probably gotten 5 other patches for the same bit, so
your patch may not be the one that gets published.
Allison
Michael Lazzaro
On Wednesday, November 6, 2002, at 10:58 AM, Simon Cozens wrote:
> It's all at http://cvs.perl.org/cvsweb/perl6/doc/design/
No, that's the Apocalypses and Exegesiii, though very nicely cleaned
up. I'm talking about detailed documentation for the things the A's
and E's don't cover.
MikeL
Angel Faus
> ideas, not-so-good ideas, and ideas with potential but desperately
> needing polish. If you'd like a recap, you might try MJD's article
> on the subject (http://www.perl.com/lpt/a/2000/11/perl6rfc.html).
> One of the major things that was lacking from the RFC process was
> focus. The advantage of community contribution is that it brings
> out good ideas from many different perspectives. The disadvantage
> is that the ideas form no coherent whole. Larry was the obvious
> choice to provide the needed focus.
The fact that the RFC process did not well as we all expected doesn't
mean that the community has to remain silent for two years, or that
the only authorized way to express should be perl6-language.
Coding is not the only useful thing we can do while we wait for the
design to finish. While Apocalypses are great to show (and justify)
the changes, they are no substitute for the a language reference, or
for user-oriented documentation.
So, while we all wait for Larry to wait the design, is there any
reason not to start working in the documentation?
This would serve for:
- Consolidating Perl5 documentation + Perl6 Apocalypses/Exegesis/..
and merging it all into a single reference.
- Finish the details that may be not complete in the Apocalypses
(there are plenty of them)
- Create tentative references for "boring" things, that may be
revised/updated with Larry's coments.
We can avoid the RFC nightmare by:
- Working in a structured way: for example replicating the structure
of perl5 documentation.
- Working _independently_ of Larry. There is no need for Larry to
spend time reading or fixing the documentation generated by the
Documentation Group.
Discussion could be done in a separate list (perl6-documentation?) and
it would be the Documentation Group's responsability to update the
documentation whenever an Apocalypses invalidates it.
It's like this: Larry writes the Apocalypses, Damian the Exegesis, and
the community writes the Cathecism (a codified, detallied and
anonymous explanation of the most boring details of the faith,
written in a form that plain people can understand).
-angel
Simon Cozens
> No, that's the Apocalypses and Exegesiii, though very nicely cleaned
> up. I'm talking about detailed documentation for the things the A's
> and E's don't cover.
Ah, well, they don't cover that. I thought that was what you were doing,
right? :)
--
So what if I have a fertile brain? Fertilizer happens.
-- Larry Wall in <2000021219...@kiev.wall.org>
Michael Lazzaro
On Wednesday, November 6, 2002, at 12:10 PM, Simon Cozens wrote:
> mlaz...@cognitivity.com (Michael Lazzaro) writes:
>> No, that's the Apocalypses and Exegesiii, though very nicely cleaned
>> up. I'm talking about detailed documentation for the things the A's
>> and E's don't cover.
>
> Ah, well, they don't cover that. I thought that was what you were
> doing,
> right? :)
AAAAAAAAAAAAAAAAAAAAAAAGGGGGGGGGHHHHHH!!!!!!!!
MikeL
Nicholas Clark
> On Wed, Nov 06, 2002 at 06:58:52PM +0000, Simon Cozens wrote:
> > mlaz...@cognitivity.com (Michael Lazzaro) writes:
> > > Big, Big HOLE in the middle. _Who_ is fleshing out the mindless,
> > > trivial details that Larry posts to this list, and _who_ is
> > > creating/updating the documentation to reflect those changes? Anyone?
> >
> > Allison is, but she was too modest to say so. (And I fear, too busy
> > to check in much in the recent past. :( )
> >
> > It's all at http://cvs.perl.org/cvsweb/perl6/doc/design/
>
> The updates to A1 are finished and pending approval. A2's updates are
> half finished. The rest of the revisions to the Apocalypses and Exegeses
> are in the form of extensive notes.
Good.
(I can't find a better way to say that without sounding insincere)
> Feel free to send me documentation patches (follow Parrot's format:
> http://www.parrotcode.org/patchfaq). They'll be accepted if they're
> clearly written, technically correct and relevant. They'll be subject to
> my edits and a review process by the entire design team. And keep in
> mind that I've probably gotten 5 other patches for the same bit, so
^^^^^^^^^^^^^^^^^^^^^^
> your patch may not be the one that gets published.
Not good. 5 patches means that 4 people wasted effort trying to help.
I don't have a solution to this problem (sorry). But I think it's an
important problem to solve.
What would facilitate the edit/review process so that the time taken to
apply a patch gets reduced?
Failing that
Is there a good way to have the apocalypse documents annotated in some way
with the lines or sections that are subject to a pending review?
If they're being sent as diffs can we automatically mangle the diffs to
replace the substituted in text with XXXXs so that anyone who is thinking of
supplying a documentation patch can at least see which parts of the docs are
already pending changes. Is it sensible to make the list of unapproved edits
available for all to read (bluntly marked as such)
Speaking for just myself, until such time as I know that there wasn't the
strong chance of 1+ patches already existing for any part of the documentation,
I won't even consider using finite supply of free time on submitting
documentation patches for perl6.
Hmm. Don't take that as a commitment that I would be supply patches as soon
as the patch pending sections are known - I suspect my finite time is better
spent on code implementing things.
Nicholas Clark
--
INTERCAL better than perl? http://www.perl.org/advocacy/spoofathon/
Dan Sugalski
>It's like this: Larry writes the Apocalypses, Damian the Exegesis, and
>the community writes the Cathecism (a codified, detallied and
>anonymous explanation of the most boring details of the faith,
>written in a form that plain people can understand).
Make these in the form of tests. Tight, small, unambiguous chunks of
code with expected behavior.
We will, I promise, roll every single correct test that comes in
patch form into the parrot source distribution.[*]
[*] Barring license issues, of course. Can't do much with tests
labelled "May not be distributed with Parrot" for example... :)
--
Dan
--------------------------------------"it's like this"-------------------
Dan Sugalski even samurai
d...@sidhe.org have teddy bears and even
teddy bears get drunk
Garrett Goebel
>
> So, while we all wait for Larry to wait the design, is there any
> reason not to start working in the documentation?
Any chance of getting a wiki setup at:
http://dev.perl.org/perl6/cathecism/
Say using a wiki which uses pod for markup like:
http://search.cpan.org/author/MSERGEANT/AxKit-XSP-Wiki-0.04/lib/AxKit/XSP/Wi
ki.pm
So people can start working on the Perl6 Core documentation, etc.?
Dan Sugalski
>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?
>
>Any chance of getting a wiki setup at:
> http://dev.perl.org/perl6/cathecism/
Wikis have serious scaling issues. Which isn't an argument against,
merely something that must be kept in mind when considering one.
Nicholas Clark
On Wed, Nov 06, 2002 at 09:57:58PM +0100, Angel Faus wrote:
> - Finish the details that may be not complete in the Apocalypses
> (there are plenty of them)
write specifications of all the detailed bits as regression tests.
code is usually more tight in its definition of things than English
Also, if I remember The Mythical Man Month correctly, Brookes said that
either the user manual or the spec can be definitive, but not both - the
other must be a derivative.
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 know what I'd prefer. Mainly because I type make test and let the computer
check that the implementation is correct (while I make myself a cup of tea
by hand). I prefer this to checking by hand and machine brewed tea.
Nicholas Clark
Allison Randal
>
> -- The "latest news" on the Perl6 section of dev.perl.org was updated
> July 7th, introducing Piers, and other than linking to Piers' summaries
> contains no information pertinent to Perl6 -- only Parrot.
Sounds like a place you might volunteer.
> I don't *WANT* to write damn documentation. I wrote a first-chapter
> summary of some basic Apocalypse 2 stuff because, a year and a half
> after it first came out, NOBODY HAD DAMN WELL DONE IT YET. Worse, I'm
> bloody *volunteering* great gobs of time to do it, and it's like
> pulling teeth to get people to agree to it!
Unfortunately we don't have time to edit and approve every summary that
every individual produces. Again, we could spend all our time on that
task alone to the exclusion of all others. The project has to keep
focus.
And yes, the review is necessary. The only thing worse than no
documentation is inaccurate documentation.
> >...you might contribute to Parrot.
>
> I would *love* to. What should I work on first...
Subscribe to p6-internals and find out where they need help.
> Again, my point is that Parrot is doing fine, and Larry is doing fine.
> But the hole in the middle -- coming up with the details so that the
> Parroteers can actually implement something, and not have to sit on
> their @$$es for a few months after they've finished the non-Perl core
> -- is getting _very_ _wide_.
The obstruction you're imagining doesn't exist. The "Parroteers" ask for
guidance from Dan. When Dan feels the details aren't clear enough yet he
brings the issue to the rest of the design team. When none of us can
give him an immediate answer (because we haven't covered it yet) and it
is an important issue standing in the way of progress in Parrot, we sit
down and hash it out until we have a clear answer.
I'm not rejecting your help. We welcome all the help we can get. I'm
merely asking (wearing my official assistant project manager hat, if it
helps) that you harness your energy to the places where it will have the
maximum benefit. And believe us when we tell you that you haven't found
the right place yet.
Allison
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.
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
Dan Sugalski
>The obstruction you're imagining doesn't exist. The "Parroteers" ask for
>guidance from Dan. When Dan feels the details aren't clear enough yet he
>brings the issue to the rest of the design team. When none of us can
>give him an immediate answer (because we haven't covered it yet) and it
>is an important issue standing in the way of progress in Parrot, we sit
>down and hash it out until we have a clear answer.
Shhh! Don't tell, but I really just make it up. ;-)
Now, to put on my cranky curmudgeon implementor's hat...
The answer's to Just Do It. (Which I know you've already done a
number of times) Try for consensus to some extent, and try to get
word on the bits that are up in the air from Larry so you've a good
chance of it being correct, but... do it. Do it, send it in to the
list, and be done with it. Unless you're covering already-well-hashed
ground, nobody'll get unhappy and if we do, well, we're adults, we
can deal with it.
In general, coordinating with Allison's a good idea, so we don't have
a dozen people doing the same thing, and so the results can be mushed
together, but there's too much to do for a single person, and none of
us like being choke points for progress.
Michael Lazzaro
people have posted on this topic to be absolutely astounding.
On Wednesday, November 6, 2002, at 12:44 PM, Allison Randal wrote:
>> I don't *WANT* to write damn documentation. I wrote a first-chapter
>> summary of some basic Apocalypse 2 stuff because, a year and a half
>> after it first came out, NOBODY HAD DAMN WELL DONE IT YET. Worse, I'm
>> bloody *volunteering* great gobs of time to do it, and it's like
>> pulling teeth to get people to agree to it!
>
> Unfortunately we don't have time to edit and approve every summary that
> every individual produces. Again, we could spend all our time on that
> task alone to the exclusion of all others. The project has to keep
> focus.
No time, because there are so many people clamoring to do it? Where??
Forgive me, but I have yet to see *any* ground-up Perl6 documentation
of comprehensive scope, other than the occasional couple-of-page
postings to the O'Reilly site. Seriously, are you saying that a
document similar to this (http://cog.cognitivity.com/perl6/val.html)
already exists, but that the design team is been unwilling to release
it for discussion? Or are you saying that (revised)
Apocalypses/Exegeses are all we're gonna get for the indefinite future,
and any community efforts to the contrary are futile?
It has been asserted in this discussion that (1) we don't need accurate
online docs yet; (2) the programming can occur (efficiently) without
them; (3) continuing to move forward on the design while the details of
previous decisions have yet to be specified is in fact the most
efficient use of everyone's time, including that of the design team;
and (4) that the community really can't offer any assistance of value
here. Those notions truly surprise me.
>>> ...you might contribute to Parrot.
>> I would *love* to. What should I work on first...
> Subscribe to p6-internals and find out where they need help.
Well, as of yesterday the most interesting topics (IMO) currently are
that Dan is describing bytecode generation (i.e. he's written some
needed docs), and the original "Need for fingerprinting" thread is
devolving into a discussion of the JIT and GC approaches & speed, as
all threads on p6-internals eventually do. They are (thankfully)
focusing on Parrot core issues, not Perl6 language-specific issues, as
they should be, and as they have been.
Seriously, don't patronize me: it won't get you anywhere productive,
and it just ticks me off. I am not _unaware_ of the current Perl6
dynamics and management decisions; on the contrary, I am observing that
the current approach has resulted in _profoundly_ little progress per
unit time, given the pool of available labor and talent at our
disposal, and has resulted in us revisiting decisions *repeatedly*
whenever previous designs are more fully worked out.
> I'm not rejecting your help. We welcome all the help we can get. I'm
> merely asking (wearing my official assistant project manager hat, if it
> helps) that you harness your energy to the places where it will have
> the
> maximum benefit. And believe us when we tell you that you haven't found
> the right place yet.
It sounds like you're pretty firmly rejecting it, when it comes to any
detailed documentation effort. So be it.
MikeL
Allison Randal
>
> Not good. 5 patches means that 4 people wasted effort trying to help.
> I don't have a solution to this problem (sorry). But I think it's an
> important problem to solve.
Wasted effort is a problem. I don't know that a perfect solution exists.
Parrot's solution of making patches public on the list seems like a
pretty good one. Asking if the work has already been done before you
take on the task also helps.
> What would facilitate the edit/review process so that the time taken to
> apply a patch gets reduced?
Some things just take time.
> Failing that
>
> Is there a good way to have the apocalypse documents annotated in some way
> with the lines or sections that are subject to a pending review?
>
> If they're being sent as diffs can we automatically mangle the diffs to
> replace the substituted in text with XXXXs so that anyone who is thinking of
> supplying a documentation patch can at least see which parts of the docs are
> already pending changes. Is it sensible to make the list of unapproved edits
> available for all to read (bluntly marked as such)
This could probably be done. But the effort involved is prohibitively
greater than simply pushing them through the review process, while the
end result -- an updated document -- is the same without the extra
effort. I wouldn't stop anyone who volunteered to set up something like
that, but we could use that time and talent elsewhere to greater effect.
> I suspect my finite time is better spent on code implementing things.
I agree. Keep up the good work.
Allison
Simon Cozens
This is getting silly.
mlaz...@cognitivity.com (Michael Lazzaro) writes:
> Seriously, don't patronize me: it won't get you anywhere productive,
> and it just ticks me off. I am not _unaware_ of the current Perl6
> dynamics and management decisions; on the contrary, I am observing
> that the current approach has resulted in _profoundly_ little progress
> per unit time, given the pool of available labor and talent at our
> disposal, and has resulted in us revisiting decisions *repeatedly*
> whenever previous designs are more fully worked out.
I think you're equating a pool of "available" talent and labor with
a pool of willing talent and labour. Everyone is willing to offer
suggestions, but few people - you being one of the few - are willing
to put the time into thrashing these suggestions out into a coherent
set of documentation.
Here is my suggested solution to the problem.
1) We find a team of volunteers who are willing to "own" the task of
converting each Apocalypse into a complete design. If nobody wants
to write the Perl 6 user manual, then we might as well give up and
go home now. So far we only need to find four, though, so it Might
Just Work.
2) Each Apocalypse gets a mailing list. Questions about a particular
topic ought to be directed to the appropriate list. (Where possible.)
3) Each "subdesigner" is responsible both for monitoring p6l and the
Apo mailing list for discussion of the topics covered, (and pointing
people to the archives where necessary) and also raising questions
when the fleshing-out process gets stuck. Delegation of some of the
process to other mailing list members is encouraged.
4) The subdesigner (or his appointed secretary[1]) summarizes the thread,
ideally in the following manner:
What does this code output?
...
I think it should output XXX, because ...
Joe Bloggs thinks it should output YYY, because ...
5) This summary is taken back to p6l, where interaction between Apocalypses
can be thrashed out. Further points are noted and added to the summary.
An arbitrary moratorium should be set when the summary is posted to p6l.
6) The summary gets sent to Allison, who circulates it to the rest of the
design team, and an arbitration is made.
7) The arbitration gets turned into two things: a test case, and a change
to the user manual.
8) Both are submitted back to Allison for checking.
Does that save any time or make any sense?
[1] You can tell I've been rereading MMM...
--
I'm surrounded by electromagnetic radiation all the time. There are radio
stations broadcasting at lots of kW, other people using phones, the police,
[...] the X-rays coming from my monitor, and God help us, the sun. I figure
I have better things to worry about than getting cancer from the three or
four minutes a day I spend on my cell phone. - Dave Brown.
Simon Cozens
> 1) There *must* be someone who will drive the discussion, or it will
> wander off into some bizarre corner and die
That's the job of the Apo pumpkin.
> 2) Under no circumstances can Larry be allowed to subscribe, or even
> read, the lists. :)
I thought that was so obvious it wasn't worth mentioning. :)
--
Do you associate ST JOHN'S with addiction to ASIA FILE?
Dan Sugalski
>I think you're equating a pool of "available" talent and labor with
>a pool of willing talent and labour. Everyone is willing to offer
>suggestions, but few people - you being one of the few - are willing
>to put the time into thrashing these suggestions out into a coherent
>set of documentation.
This is an important observation most people miss. You can (and I've
dealt with quite a few) find people who will spend hours, days, or
weeks of their lives writing email discussing some damn thing or
other that doesn't exist, yet never actually make that thing exist
even if it'd only take an hour or two to do.
>Here is my suggested solution to the problem.
And, though, snipped, a fine solution it is, with two caveats:
1) There *must* be someone who will drive the discussion, or it will
wander off into some bizarre corner and die
2) Under no circumstances can Larry be allowed to subscribe, or even
read, the lists. :)
Michael Lazzaro
On Wednesday, November 6, 2002, at 03:34 PM, Dan Sugalski wrote:
> At 11:15 PM +0000 11/6/02, Simon Cozens wrote:
>> Here is my suggested solution to the problem.
>
> And, though, snipped, a fine solution it is, with two caveats:
>
> 1) There *must* be someone who will drive the discussion, or it will
> wander off into some bizarre corner and die
>
> 2) Under no circumstances can Larry be allowed to subscribe, or even
> read, the lists. :)
I would also add the observation that there really only need be one
discussion, going through the issues in series... The higher-numbered
issues depend pretty extensively on details of the lower-numbered ones;
plus, I think having the same dedicated voices, ongoing (rather than
different voices working in parallel) would achieve better results and
still be sufficiently fast
Plus, one group would not be nearly as distracting to the ongoing
design efforts as it would be to have N groups all pinging with
questions simultaneously, which is what we already have. :-/
MikeL
Dan Sugalski
>d...@sidhe.org (Dan Sugalski) writes:
> > 2) Under no circumstances can Larry be allowed to subscribe, or even
>> read, the lists. :)
>
>I thought that was so obvious it wasn't worth mentioning. :)
It's the blatantly obvious stuff that gets missed the most. ;)
Allison Randal
> Simon Cozens wrote:
>
> >Here is my suggested solution to the problem.
> And, though, snipped, a fine solution it is, with two caveats:
There's potential here. If we arrange it so Larry can stay focused and
the total productivity of the project increases, we'll have a good
thing. Let's fill in the details as we go.
Michael, why don't you talk to Casey West? He'll have valuable insights
from his experience with the Perl 5 documentation project.
Allison
Andy Wardley
[...some good points...]
> and has resulted in us revisiting decisions *repeatedly*
Simon Cozens wrote:
[...some good ideas...]
> [1] You can tell I've been rereading MMM...
Maybe there's some benefit to be had from revisiting old material? :-)
I can't think of any non-trivial piece of software I've written
without going over the design several times...
....just like I can't think of any great book that I've fully appreciated
without reading through it several times.
Sometimes the Perl 6 design process looks like a machine that's running
fast but moving forward slowly, churning over the same ground. But in
this case, the purpose of our vehicle is to plough the ground. We're
more concerned about tilling the soil than getting to the other side
of the field as quickly as possible. From that perspective, it looks
to me at least, like we're making much better progress.
Well, "we" meaning "you". I'm no use to anyone - my head exploded days
ago in a big mess of Unicode operators. <<*[BOOM]*>>8-|
raptor
to cover not only Perl - OOP, but the whole Pel6.
http://cog.cognitivity.com/perl6/contribute.html
ooops.... i see u are the admin of this :"))
nice work... keep going.....
raptor
Angel Faus
> 1) We find a team of volunteers who are willing to "own" the
> task of converting each Apocalypse into a complete design. If
> nobody wants to write the Perl 6 user manual, then we might as well
> give up and go home now. So far we only need to find four, though,
> so it Might Just Work.
I would prefer to work from perl5 documentation. Because:
- some documents can be already written, even when there is not yet an
Apoc tallking about them. (for example, "perlvar" shoud be reasonably
easy)
- Apocalypses talk about a big number of issues, while perl5 pods are
already structured in documents of reasonable length.
- The sorther length of perl5 pods documents makes it much easier for
a single person to make the specific task.
People would volunteer for a document, and write and send it for
review in a separate list from perl6-language.
There should be someone to finally aprove the tentative version. It
could be someone with experience in perl5 documentation, and not
necessarily from the design team (because the task is about
documenting, not creating).
-angel
Michael Lazzaro
>> 1) We find a team of volunteers who are willing to "own" the
>> task of converting each Apocalypse into a complete design. If
>> nobody wants to write the Perl 6 user manual, then we might as well
>
Unfortunately, after doing lots of initial outlining, I don't see a
whole lot of useful correlation between them anymore. :-/ The perl5
pods are not terribly detailed compared to what we need, and there's so
many changes in the "fundamentals" of the language that we really have
to explain and support it in a much more sophisticated way, if we want
the language to grow. So I've become fairly convinced we need to
rethink the docs, just like we're rethinking the language.
So far, I have experimented with two approaches ... the "annotated
recipes" approach (1), and the "booklike" approach (2):
example 1: http://cog.cognitivity.com/perl6/1_intro/6.html
example 2: http://cog.cognitivity.com/perl6/val.html
to check out how they both would feel online.
The "annotated recipes" approach is an *excellent* format for a
document to be constructed in, since it allows realtime feedback from
people -- you can post your proposed changes right there, and have them
reviewed, without anyone duplicating effort and without
checkin/checkout/patch issues. It's self-organizing, and it doesn't
need teams -- people can contribute when and how they like, to whatever
they like. Good when dealing with lots of opinionated but lazy people.
;-)
OTOH, the "booklike" approach is much easier (for me, at least) to
write *large* chunks of documentation very quickly, but is more
difficult to contribute to. There's probably a happy medium here
somewhere.
After experimenting, I myself have been gravitating towards the online
mysql (http://www.mysql.com/documentation/) documentation as the best
example of what I think we need for a "final version". Maybe. Check
it out and see what you think.
I dunno anymore, maybe we need to rethink what place there is for
public domain docs at all. Perhaps we just have a man page that says
"buy the damn books, you cheapskate" and be done with it.
MikeL
David Dyck
> I dunno anymore, maybe we need to rethink what place there is for
> public domain docs at all. Perhaps we just have a man page that says
> "buy the damn books, you cheapskate" and be done with it.
I trust you were joking, right?
I learned perl3 by reading the 62 pages of the manual.
I learned perl4 by reading the 76 pages of the manual,
and then bought the book.
For perl5 I read much of the manual, and bought and read 4 books.
(there are nearly 2000 pages of pod documentation for perl5.9,
not counting the perldoc of the installed modules).
I expect that perl6 will have more online documentation,
and I'll probably learn from the new books I purchase.
With out authoritive online documention I don't think
that perl6 will go anywhere.
Allison Randal
Let's table discussion of the details for a few days until we get the
perl6-documentation list set up. Then we can dig into planning out the
scope and goals of the project, and what roles various people might
take.
Allison
Allison Randal
> Subscribe by sending mail to perl6-document...@perl.org.
> NNTP access and archives at nntp.perl.org will be available a few
> hours after the first posting to the list.
Let the games begin...
Allison
Piers Cawley
Those of us with subs to perl6-all will get this anyway, right?
--
Piers
"It is a truth universally acknowledged that a language in
possession of a rich syntax must be in need of a rewrite."
-- Jane Austen?
Michael Lazzaro
On Thursday, November 7, 2002, at 10:45 PM, Piers Cawley wrote:
> Those of us with subs to perl6-all will get this anyway, right?
I posted an initial message about five minutes ago, so if you received
it, then yes. :-)
MikeL
Markus Laire
There are few messages going there now, but at least I don't receive
them via perl6-all, only via perl6-documentation
(I'm on both lists, just in case)
--
Markus Laire 'malaire' <markus...@nic.fi>
Piers Cawley
Ah... that would explain why I haven't seen it then. Looks like
someone broke perl6-all.
Robert Spier
>someone broke perl6-all.
No, it was just "not configured".
Future messages to perl6-documentation should end up on perl6-all.
-R