From: Jim Freeze <jim@...>
Date: 2002-09-05T19:52:49+09:00
Subject: Re: suggestions to the Ruby community

On Thu, Sep 05, 2002 at 02:30:15PM +0900, Hal E. Fulton wrote:
> ----- 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.

That is fine, but I don't want to overburdern this list.
BTW, who could setup a ruby-doc@ruby-lang mailing
list for us?

> 
> >  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.
 
How about RDSC (Ruby Documentation Standardization Committee)
Not particularly clever, just an acronym.

> >  3. Start a web page to publicize the activities
> >     of the documentation project.
> 
> Great.
> 
There are several that already exist. Should this effort be
on the main ruby-lang site (ruby-lang.org/docs) or on 
its own?

> >  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.
> 
Well, if its make you feel better we can reword it:

   a. Gather stories
   b. Programmers prioritize stories
   c. Programmers choose stories and outline their effort

:)

I agree that a-c sound monolithic. My intent was to get
the scope defined so more people could help. My particular
style is that the requirements document in (a) is just a page
or two. The functional document in (b) defines the user
interface (for now probably mostly command-line). And
the design document is (dare I say it) optional.

> 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!
> 

-- 
Jim Freeze
----------
Programming Ruby 
 def initialize; fun; end
A language with class