Re: Ruby Docs with annotations and searching

Conor Hunt wrote:
> I really do like the way the PHP docs work, I don't know what they do
> in the background, but I have found incredible use from the comments,
> usually the comments are more useful than the official documentation!
> I have heard many times "why doesn't Ruby or Rails have documentation
> like PHP?" 

I don't want to sound too negative, but you seem to be assuming that the 
reason Ruby doesn't have good documentation, is that it doesn't have 
easy ways to write documentation.

I believe that's not the case, and that the reason Ruby doesn't have 
good documentation is (a) historical and (b) cultural.

The historical aspect is that a lot of Ruby code was written by Japanese 
people who either didn't write English documentation, or had trouble 
making their English documentation clear. No fault of theirs, of course, 
I'm just saying that's part of how we got here.

But the second aspect, the big one, is that for reasons I don't quite 
understand Ruby seems to have attracted a lot of people who actively *do 
not believe in documentation*. I've literally been flamed for daring to 
suggest that documentation is essential to good code, and that unit 
tests are not a substitute for documentation. (Watch, maybe it'll happen 
again now.)

I also suggested that there should be a moratorium on adding 
undocumented (and hence unrefactorable) code to Ruby. That suggestion 
was met with mostly silence, plus a little "take it to another list" 
hostility.

Rdoc makes it ridiculously easy to write at least minimal documentation 
while writing the code. If the people updating code are so misguided or 
lazy that they won't jot down a few lines of comments while they've got 
the code open in their text editors, they're not going to go to some web 
site and navigate around to the right place and write it there. The 
people going to the web site will mostly be people who don't know how 
the code works.

Hence my guess is that an "annotated Ruby documentation" site will fill 
up with questions. Yes, it may attract some people who take the time to 
answer the questions, but basically it'll be another ruby-talk, only 
scattered across thousands of web pages. Who ever takes the time to read 
through ruby-talk, look for things that should be incorporated in 
documentation, and update the Rdoc? Me and, what, 2 or 3 other people? 
Given that, how likely is it that the nuggets buried in threads on this 
proposed site will ever make it into organized, structured 
documentation, assuming nuggets appear in the first place?

So what's my alternative? Simple: instead of spending time getting this 
web site off the ground and managing it, use that time to write some 
documentation.

It seems to me that everyone wants to build fancy new documentation 
processors and fancy documentation web sites so that *other people* can 
write documentation; the problem is, *nobody wants to actually write the 
documentation*. Prove me wrong, sit down and write some.

Pick a library, ideally one you've used. See if the source code has some 
comments, a README, some examples, or any other starting points. If the 
source is impenetrable, fire up irb and toy with the library until you 
work out what it's doing. Ask for clarification or assistance on 
ruby-talk or on this list.

If you have to, leave bits of the library undocumented. There's no shame 
in doing an incomplete job, it's better than no job at all. For 
instance, I skipped net/ldap when I did net/everythingelse, because I'm 
quite happy to admit I know practically nothing about LDAP and have 
always found it impenetrable.

Of course, if you want to go ahead with the web site, I've nothing 
against that. I just don't think it'll be as productive a way to 
generate documentation as actually writing documentation. If I'm wrong, 
that's good too.


mathew