From: James Britt <jamesUNDERBARb@...>
Date: 2004-07-06T15:14:01+09:00
Subject: Re: Ruby Advocacy/Documentation/Sponsorship?

Randy Lawrence wrote:
> Having discovered Ruby recently and falling in love with it, I'm 
> wondering if there are any REMAINING reasons why Ruby isn't as 
> widespread as some of the older (less-productive) scripting languages.
> 
> Is there a perception that Ruby still lacks decent documentation?

Yes, because it does.

> Does lack of corporate backing hurt more than it helps?

Depends, but having a Big Name behind Ruby would likely help.

> Should RubyForge and RAA be merged into a single archive with an 
> interface similar to CPAN?

Something along those lines would be a good thing.  At the least, 
hosting an project on RubyForge should automatically add an entry to the 
RAA.

> Is there a Ruby advocacy group?

You're soaking in it!

> 
> I'm assuming the lack of English documentation was the major barrier 
> before 2002.  IMHO, documentation now exists but they are scattered or 
> hard for newcomers to find (ie compared to Perl).  A Ruby search engine 
> covering multiple websites would be really nice, starting with these 
> docs (maybe we can get a corporate sponsor to host the search engine):

Well, ruby-doc.org is or should be that search engine, albeit with a 
good deal of human intervention.  When I learn of a new Ruby resource, I 
try to get it listed on ruby-doc.org.

However, the navigation of the site leaves much to be desired, so I've 
been redesigning the look and feel as well as the server code.  Ideally, 
anything document, video, mp3, code sample,  isbn, wtc related to Ruby 
should be locatable on ruby-doc.org, and in a variety of ways.

One should be able to query or drill down, for example, to find code 
samples on Web development that interface with C-based libraries, or 
videos that mention database programing, or tutorials for newbies with a 
functional language background.

> 
> 1. RUBY BOOKS/GUIDES
> 
> 2. RUBY CLASS/API REFERENCE
> 
> 3. RUBY CODE SNIPPETS
> 
> 4. RUBY AND C/C++ INTEGRATION
> 
> 5. MOD_RUBY+ERUBY, CGIKIT, ETC.
> 

Thanks for the list.

I'm looking for suggestions on how to organize/classify Ruby 
documentation (including tutorials, reference works, videos, blogs, 
wikis, translations, and so on).  Some of your list matches what I've 
been working on, some are good additions.

Questions:
  * What should people expect to find at www.ruby-doc.org?

  * How should it behave?

  * What goes on the front page?

My basic belief is that the site need not host much; it *could*, but 
that presents logistical and admin issues. However, one should be able 
to search *just* ruby-doc.org and get back references that tell you 
where to find the actual content you want.   It would serve as an 
annotated map of the Ruby documentation uuniverse.


Thanks,


James Britt
jbritt AT ruby-doc DOT org