From: James Edward Gray II <james@...>
Date: 2006-03-07T23:48:06+09:00
Subject: Re: No documentation for modules on RubyForge?

On Mar 6, 2006, at 11:29 PM, Aaron Becker wrote:

> Warning: flames ahead...

That's disappointing.  If you know you're out of line, you could fix  
it before you send the message.

> My opinion is Ruby is doomed if it doesn't enforce some type of  
> quality
> control on modules and general usability.  This is especially true for
> the gotchas new users will face.

What have you done to improve the new user experience?  This is an  
open source community, so we all need to be doing our part.

I've documented four standard libraries now and I run the Ruby Quiz,  
so I'm sure trying to do mine.

> Why not have a checklist of requirements for accepted modules?  I used
> gem to install "stomp" but there is no documentation and not even a
> synopsis in the code.

Who said gems are "accepted modules?"  Anyone can release gems, so  
there is no process here.

You are welcome to post a Best Practices Gem Checklist, but you need  
to keep in mind the two things you didn't when sending this message:   
we may not agree on all points and most people releasing Ruby  
libraries are working for free.

> Has anyone analyzed the most likely stumbling blocks for new  
> users?  Has
> anyone done a usability study on new users?

Will you be funding that?

> The same goes for 'reliable/msg'.  It has no documentation.  And it's
> claimed to be 'stable'???  WTF?

Whether or not code is "stable" and has documentation are not  
remotely related.

> Can�t someone write a simple webrick app to navigate the symbols and
> namespaces at run-time?

Sounds like you just found your first project to make Ruby better.

> And where is a cookbook or snippet site for Ruby code?

http://www.oreilly.com/catalog/rubyckbk/index.html

> And what about the ability to search Ruby-talk archives?

http://ruby-talk.org/ruby/ruby-talk/index.shtml

> Surely Google could help with that.

Yes, you can do it that way too:

http://groups.google.com/group/comp.lang.ruby

> You can spray a dog turd with gold paint, but it's still a dog turd.
> Hopefully, you can make Ruby live up to the hype...  And soon.

This was the absolute wrong way to win us over to anything you had to  
say.  Perhaps you have heard the phrase, "You can catch more flies  
with honey?"

James Edward Gray II