From: Alex Chaffee <alexch@...>
Date: 2011-08-08T06:42:37+09:00
Subject: Re: Brainstorming ideas how to improve Ruby's documentation

On Fri, Aug 5, 2011 at 2:27 AM, Alexander Litvinovsky
<alexander.litvinovsky@gmail.com> wrote:
> What are you talking about? Ruby has a nice docs, railsapi.com for example.
>

I think you just made the case that Ruby *doesn't* have nice docs. If
people have to go to a site called "railsapi" to get the *ruby* api
then something is wrong. :-)

FWIW, I pretty much agree with Marc Heiler... although I have to say
his post crossed the line from passionate to obnoxious.

Whenever I teach Ruby (which I've been doing a lot lately) I have to
tell a too complicated story about docs. There are some pretty big
problems with the state of Ruby Docs, and they go beyond frames and
searchability. Here's a list off the top of my head.

...and before you read the list, I hope you don't think I'm whining!
I'm pointing out specific problems with specific tools and information
designs, and I'd be happy to help fix some of them if I can (and if I
get support from key core members).

http://www.ruby-doc.org is hard to use -- the front page has TMI,
http://www.ruby-doc.org/core/ doesn't cross-link to
http://www.ruby-doc.org/stdlib/ , there's no clear "read this then
that" path...

There are several web sites that make ruby API docs searchable and
better organized, e.g. http://railsapi.com/ and http://gotapi.com.
However, they don't fix some of the core problems of rdoc. Even
without frames (darkfish ftw!) rdoc makes too many words hyperlinks to
the wrong pages, it has unmemorable and randomly changing anchor link
names, it often links to a page describing a *file* instead of the
documented *class* inside that file, and more.

http://www.ruby-lang.org/en/documentation/ has a whole bunch of links
to other sites; again it feels like information overload.

For command-line docs, ri works pretty well, but the ri db is not
installed by rvm (!!!), and many people ritually install gems with
--no-ri --no-rdoc because generating the documentation often makes the
install take 3x as long (and the whole world has ADHD these days so 3x
is unacceptable).

(By the way, would it be so horrible if "gem install" forked off a
process to build the docs in the background? On systems that support
fork, of course.)

-- 

Alex Chaffee - alex@cohuman.com - http://alexch.github.com
Stalk me: http://friendfeed.com/alexch | http://twitter.com/alexch |
http://alexch.tumblr.com