Re: Ruby Docs with annotations and searching

mathew wrote:
...

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

But there are people working quite hard, with little fanfare, adding 
quality documentation for Ruby libraries.

It's just considered unsexy by many.

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

Perhaps, but I believe the trend now i for people updating code to also 
add a few docs.  Could be wrong.  ruby-doc updates the rdoc for core and 
std-lib every night, so maybe someone can spot the improvements.

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

The PHP.net site seems to do OK, though, for various reasons, I do not 
spend much time there, so perhaps the quality is not what I imagine it 
to be.  I can see the value of having intelligent annotations to Ruby 
docs; the most effective approach, though, is unclear.


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

Indeed.  See

   http://ruby-doc.org/stdlib/
and
   http://stdlib-doc.rubyforge.org/rdoc/index.html

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

I agree with the broader sentiment, but want to emphasize that there 
*are* people in Rubyville, such as Gavin Sinclair, William Webber, Lyle 
Johnson, and James Edward Gray II,  writing docs.


Of course, more are welcome.

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

See also

http://ruby-doc.org/stdlib/status.html




James Britt