From: David Masover <ninja@...>
Date: 2009-02-16T19:21:21+09:00
Subject: Re: Good GUI documentation

Chad Perrin wrote:
> While I disagree with a lot of what 7stud says, I do believe that good
> documentation is rather more important than you make it sound.
> Sometimes, I don't want to *have* to read the source in order to use the
> library -- or, in some cases, the application.

That is very true, and good documentation is very important.

However, I stand by what I said. Unless the documentation is 
comprehensive, including a thorough HACKING document for how to start 
playing with the internals, there's always the chance with any library 
that I might have to dig into it and find out what's going on. The 
longer and more extensively I use a library, the more likely this is, no 
matter how good the docs are.

So, while I would like to be able to get that library's equivalent of 
"Hello World" working without having to read source, and while I do 
appreciate a good README at least, I'd say from there on, the importance 
of documentation vs clean code drops sharply.

As an example: Kernel#autoload is reasonably well documented. It claims 
to use 'require' under the hood. However, when I click "view source" in 
the rdoc, I get a pile of C which isn't really understandable, at least 
to me. It's also not very monkey-patchable.

So while the docs were great to get it working:

autoload :Foo, 'lib/foo'

they were problematic when I wanted something more dynamic -- and 
there's really no way to do:

autoload :Foo do
  require "some/#{interpolated}/value"
end

I even tried overriding Kernel#require, the way Rubygems does. And 
autoload doesn't seem to use that custom require.

Contrast this to Rubinius. While I haven't tried this, it just took me 
maybe five minutes on Github, without looking at any documentation, to 
find where autoload is defined, and how it it works, and how to get the 
effect I wanted (arbitrary code executed when the autoload is 
triggered), probably even with the syntax I wanted -- all of which, if 
there's a way to do in MRI, it probably requires intimate knowledge of C 
and the MRI/YARV internals.

I think I found a grand total of two comments, each one line, maybe five 
words.

Now, granted, the Ruby docs can probably be used for much of Rubinius, 
to at least find out what it's supposed to do. But I should stress 
again: MRI has good documentation via rdoc, but I just fell off a cliff 
when it came to extending. Rubinius doesn't have documentation on its 
website at the moment (though it is in the source tree), but I didn't 
need the docs to figure it out.