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?
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:
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.
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.
mlazz...@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. :( )
On Tue, Nov 05, 2002 at 04:26:58PM -0800, Michael Lazzaro wrote: > 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.
On Tue, 05 Nov 2002 23:18:01 -0800, Allison Randal wrote: > 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.
On Wed, Nov 06, 2002 at 06:58:52PM +0000, Simon Cozens wrote: > mlazz...@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. :( )
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.
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.
> 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 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).
mlazz...@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? :)
-- So what if I have a fertile brain? Fertilizer happens. -- Larry Wall in <200002121919.LAA27...@kiev.wall.org>
On Wednesday, November 6, 2002, at 12:10 PM, Simon Cozens wrote: > mlazz...@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? :)
On Wed, Nov 06, 2002 at 01:50:10PM -0600, Allison Randal wrote: > On Wed, Nov 06, 2002 at 06:58:52PM +0000, Simon Cozens wrote: > > mlazz...@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. :( )
> 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.
>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
Wikis have serious scaling issues. Which isn't an argument against, merely something that must be kept in mind when considering one. -- Dan
--------------------------------------"it's like this"------------------- Dan Sugalski even samurai d...@sidhe.org have teddy bears and even teddy bears get drunk
I'm going to repeat what chromatic said (even though I've deleted his message)
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.
On Wed, Nov 06, 2002 at 10:54:23AM -0800, Michael Lazzaro wrote:
> -- 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.
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.
>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. -- Dan
--------------------------------------"it's like this"------------------- Dan Sugalski even samurai d...@sidhe.org have teddy bears and even teddy bears get drunk
My apologies for one more post, but I find the assertions various 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.
> 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.
mlazz...@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.
d...@sidhe.org (Dan Sugalski) writes: > 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? - Henry Braun is Oxford Zippy
>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. :) -- Dan
--------------------------------------"it's like this"------------------- Dan Sugalski even samurai d...@sidhe.org have teddy bears and even teddy bears get drunk
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. :-/