[Vit-discuss] content refreshness or lack of [was Brainstorming]
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
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
> 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
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
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