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

Douglas Livingstone rampant at gmail.com
Thu Feb 24 12:11:54 EST 2005


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

It doesn't matter who writes the docs, but there has to be someone to
say "this documentation corresponds to this download of this version
of Ruby". Putting the two parts in different places with no clear
correlation just seems like an excersise in politics to me, a "we
wrote them so we want to host them" attitude which doesn't help people
learn Ruby.

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

It all depends on how the documentation is written and presented. At
the moment the core docs are not new-user friendly. The best resource
I've found online is the pickaxe, though it is out of date. Perhaps
there are other resources... If a redesign does not let me say to
someone "Download Ruby and read about what you are downloading from
ruby-lang.org" then that wouldn't be much more progress than where it
is at the moment. With PHP the docs are hosted all over the place, but
one click from the php.net front page and you've got access to all the
docs you need.

Douglas


More information about the vit-discuss mailing list