[Vit-discuss] content refreshness or lack of [was Brainstorming]

Ben Giddings bg-rubytalk at infofiend.com
Wed Feb 23 23:24:20 EST 2005

On Feb 23, 2005, at 20:10, James Britt wrote:
> For example: I believe that the ruby documentation project has helped 
> improve the state of Ruby documentation and that ruby-doc.org has 
> played an important role.  The RDP and the documentation progress 
> would have been greatly slowed or nonexistent if I had to go through 
> ruby-lang admins to host ruby-doc content and services as a sub-site 
> of ruby-lang.

Ok, but what about the idea of promoting (in the employment sense, 
rather than the advertising sense) good information to the 
ruby-lang.org site.

I'll pick my favourite example: the API and stdlib docs.  I *really* 
think they should go on the official ruby-lang.org site.  Here's an 
example of why.

In the "Best ways to accelerate Ruby's popularity" thread, Navindra 
Umanee said:
> As someone who's been lightly dabbling with Ruby recently (and is not
> about to stop), you make several good points.
> I can't get rid of the lingering feeling that Ruby is still somewhat
> immature/unpolished.  Part of the reason is lack of documentation and
> sometimes the documentation that I do use is plain wrong or
> out-of-date because the Ruby API changes from release to release.  Of
> course, I'm using RubyCentral for most of my documentation needs --
> they've done a fantastic job, but that's hardly official or
> up-to-date.

then followed it up with:

> Ah, is ruby-doc.org the official source of Ruby documentation then?
> http://www.ruby-doc.org/core/ seems a bit overwhelming.

That's the whole reason I think that certain resources really should be 
hosted on ruby-lang.org.

ruby-doc.org is a great resource, and contains a whole lot of 
resources, most of which don't need to be hosted at ruby-lang.org, like 
"FOX + RUBY = FXRuby Par l'exemple".  On the other hand, I think the 
API and stdlib docs are essential enough that they should become the 
"official source of Ruby documentation", and that should be made clear 
by hosting them at ruby-lang.org.

Maybe I'm alone in this, but I strongly believe that a newcomer to 
Ruby, looking for documentation on the language wants to find "the 
official API documentation" rather than "the documentation some Ruby 
enthusiast put up".  If the documentation is on ruby-lang.org, that 
makes it clear that it's official.  If there's a link from 
ruby-lang.org, that suggests the documentation is approved, but not 
necessarily official.

It also makes sense that the API docs be on ruby-lang.org so that when 
a new version of Ruby is released on the site, the API docs can be 
updated at exactly the same time.

That's my sales pitch.  I'm picking the API docs because to me they're 
the most glaring thing missing from ruby-lang.org, but I think there 
are a few other things missing.  Hopefully we can fill in those gaps, 
link to the somewhat less essential resources, and end up with the ruby 
site of my... I mean our dreams.  ;)


More information about the vit-discuss mailing list