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

Zach Dennis zdennis at mktec.com
Wed Feb 23 23:43:09 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 
> 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.

who declares official?

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

This is probably how the documentation is laid out, hardly the url that 
gets Navindra there.

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

Both of those suggest some things, but neither strike me as them needing 
to be hosted by the ruby-lang.org server. If it happened great, but if 
you are looking at the url to where you are to determine if something is 
"official" then you are hardly there for the language.
> 
> 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". 

So have the ruby0doc.org crew put in their title bar of the Internet 
Browser "Official Ruby Language Documentation Web Site". If the 
ruby-lang.org site says that the official docs can be found at 
ruby-doc.org and there is a link to that site i think the user will get 
the point, and they will get to the docs





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

I dont buy the "official", "non-official" thing in the context of 
ruby-lang.org. Anyways, I think this can be brought up at a later date 
when it's more in context. We need to get the site up to par and the 
functionality and experience for the user down pat first (as well as the 
GUI). Once that is done, and the docs move to 
http://www.ruby-lang.org/docs then just update the links on the 
ruby-lang.org site. Easy as pie. No need to have such a big debate about 
it now.

> 
> 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.  ;)
> 

I see what you want, I don't disagree with it entirely, but at this 
point in the process I don't think it's very important. I think we 
should revisit this once some other groundwork is done first.

Zach


More information about the vit-discuss mailing list