Re: perl6-lang Project Management

[Michael Lazzaro]

On Thursday, November 7, 2002, at 03:44  AM, Angel Faus wrote:

   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

I would prefer to work from perl5 documentation. Because:

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