[Vit-discuss] content refreshness or lack of [was Brainstorming]
james.britt at gmail.com
Thu Feb 24 08:48:23 EST 2005
Ben Giddings wrote:
> 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
I don't understand your phrasing, "promoting good information to the
ruby-lang.org site." Do you mean having links back to ruby-lang.org?
That's certainly appropriate.
> 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.
There should be obvious links tot he core and std-lib docs on
ruby-lang.org. Whether the should hosted there is a other matter. I
would argue that they should, but it isn't essential.
> 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
The issue here may be that there are multiple sites hosting Ruby docs,
but not hosting the most recent docs. I believe the above comment
refers to a reference work on RubyCentral that covered Ruby 1.6.
People would do better to use ruby-doc that RubyCentral for
documentation, but ideally is shouldn't matter; the docs are easy to
generate or download, so any site that wants to mirror them can easily
> 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.
Would http://www.ruby-lang.org/core/ be less overwhelming?
> 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
> 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".
They are the same thing. Pretty much everything in Rubyland happens
because of enthusiasts. Perhaps new comers would have an easier time if
the doc links were on ruby-lang.org, but I have a hard time believing
that if those links went to another site that the user would find the
docs less useful or authoritative.
My main concerns with what gets hosted where has more to do with
enabling faster growth and more responsive behavior by distributing work
and resources. Hosting the docs is trivial, so I have no beef with
having them on ruby-lang.org. So long as everyone hosting the docs has
the latest version and everyone stays in sync. So I would suggest that
ruby-lang use a cron job to download docs from ruby-doc.org. (Just
don't run it every 2 minutes.)
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.
That's an substantiated claim, but I've pretty much said all I can say
on this. See above and about a dozen other posts from myself and a some
others. Truth is, I've heard dozens of people tell me what a great
resource ruby-doc is (though all real props go to the doc writers), and
not a single person has said they they personally felt the docs were
less than official or authentic.
More information about the vit-discuss