Newsgroups: perl.perl6.language
Path: archiver1.google.com!news1.google.com!newsfeed.stanford.edu!nntp.perl.org
Return-Path: <mlazz...@cognitivity.com>
Mailing-List: contact perl6-language-h...@perl.org; run by ezmlm
Delivered-To: mailing list perl6-langu...@perl.org
Date: Thu, 7 Nov 2002 10:38:49 -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: perl6-langu...@perl.org
To: af...@corp.vlex.com
In-Reply-To: <200211071244.23892.afaus@corp.vlex.com>
Message-ID: <28191793-F280-11D6-8A7C-00050245244A@cognitivity.com>
Content-Transfer-Encoding: 7bit
X-Mailer: Apple Mail (2.546)
X-SMTPD: qpsmtpd/0.12, http://develooper.com/code/qpsmtpd/
Approved: n...@nntp.perl.org
From: mlazz...@cognitivity.com (Michael Lazzaro)
References: <200211071244.23892.afaus@corp.vlex.com>
Lines: 48

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