----- Original Message ----- 
From: "Jim Freeze" <jim / freeze.org>
To: "ruby-talk ML" <ruby-talk / ruby-lang.org>
Sent: Wednesday, September 04, 2002 11:02 PM
Subject: Re: suggestions to the Ruby community


>  1. Form a ruby-doc mailing list to begin discussions
>     related to documentation.

Fine idea. I support it, but I'm too overcommitted
to actually join it.

I wonder if it should be kept with the main list
for a while? Maybe split it off only when traffic
gets too great.

>  2. Form a Ruby Document Organizing Committee (RDOC)
>     for purpose of officially reviewing the document 
>     standardization process and voting on
>     decisions (of course Matz has ultimate veto power).

Calling it RDOC is cool and clever... but I'd suggest
using some other name. We don't want people saying "the
committee, not the tool" or vice versa. And we don't 
want searches for one to turn up the other.

>  3. Start a web page to publicize the activities
>     of the documentation project.

Great.

>  4. Start the paper work for the standardization process.
>     a Gather Requirements and write Requirements specification.
>       i. get feedback from community
>       ii. have committee review and approve
>     b. Write functional specification
>       i. get feedback from community
>       ii. have committee review and approve
>     c. Create design document
>       i. get feedback from community
>       ii. have committee review and approve
>     4. Implement RDOC process and develop tools
>     5. Integrate 4 into releases of Ruby

This is good, but it sounds a little monolithic
to me. I think an XP-like approach might be 
better.

That's up to the people working on it, of 
course. But beware of two things: 1) The 
process-for-the-sake-of-process syndrome,
where more paperwork and red tape are 
generated than actual progress made; and
2) the "scope creep" syndrome, where nothing
is ever releasable because a cool new feature
is currently being added.

> I welcome your comments along the lines:
> 
>   a) this is a good idea, let's get going
>      and I want to be on the committee
>   b) what, are you crazy??

Are a and b mutually exclusive?  :)

>   c) good idea, but I can do a lot better
>      job than you...
>   d) it's all hopeless, I am going back to
>      programming in perl.

I think it's great that this is turning into
a project of its own.

And just think, it started from someone on the
list saying, "Why can't you guys get your act
together?" :) No flames! It's a paraphrase!

Hal