From: Randy Lawrence <jm@...>
Date: 2004-07-07T03:29:02+09:00
Subject: Re: Ruby Advocacy/Documentation/Sponsorship?

James Britt wrote:

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

James,

Thanks for the detailed response and thanks even more for providing 
ruby-doc.org!!! The ruby-doc.org site is VERY appreciated.

In terms of some suggestions...

1. The primary links (documents..., downloads...) should be made much 
more obvious (larger font and/or more menu-like in appearance).  It 
might even fit on a left vertical menu if you want to try it out.

2. The text used for primary links (primary menu) should make sense to 
noobs (ie they don't know terms like "PickAxe"). Here's one possible 
selection of the primary links (in all caps).  For a "top menu" 
scenario, probably 1-4, and 7.  For a "left menu" scenario, they'll all 
fit (submenus might not).

START
	Intro to ruby-doc.org (for noobs)
	Recommended reading
	Recommended downloads (ruby, must-have 3rd-party libs, etc.)

1. ARTICLES
	Intro to Ruby
	...	

2. BOOKS
	ONLINE
		Programming Ruby (Pickaxe)
		...
	PURCHASE
		Amazon/Bookpool links ($ to help pay for ruby-doc.org)
		...

3. CLASS/API REFERENCE
	core api
	stdlib
	...

4. CODE EXAMPLES/SNIPPETS
	pleac_ruby
	...

5. GUI
	FOX
	TK
	WX
	...

6. SERVER-SIDE
	CGI
		mod_ruby
		eruby
		cgikit
		...
	DATABASES
		DBI
		MySQL
		PostgreSQL
		SQLite
		...
	DISTRIBUTED (DRB)
	WEBRICK	
	...
		
7. SEARCH
	simple or complex search forms on this page

8. USEFUL TOOLS (stable 3rd-party libraries)
	Log4r
	...

9. USING C/C++/JAVA/...
	C/C++ with SWIG
	JRuby
	...