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

[James Britt]

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

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.

<snip/>

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
>> up-to-date.


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 
do so.


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

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.


James