Jeremy McAnally wrote:
> Indeed.  I've started work on a really nice utility to make working on
> Ruby documentation very easy, but it's been slow.  I'm hoping to have
> something to show very soon...

This sound fantastic!

Let me know if you want any ideas! Here are some obvious ones:
1. The utility you're now building also must have state-o-the-art 
documentation (good and well-organized tutorials, index, good template, 
etc). Setting good examples are of course important.
2. That your utility includes a few help templates. You could for 
example ask the authors of existing templates (such as "jamis" and 
"Allison") if the could distribute those.
3. That your utility bundles a few PD icons for often-used situations 
(code samples, exclamation point, question mark, etc)

> Until then, I'm not sure what to do to stimulate people to document.

I think the key actually is in the blog post that started this whole 
long thread (about American culture not having a conceptual word for 
what Ruby really stands for). If there's a mantra going that Ruby is 
designed to make programmers feel good, it should be pretty evident that 
bad documentation disrupt that feel.

Another thing: there are 100's of web sites on how to program in Ruby, 
but is there any site on how to write documentation for Ruby 
programmers? And I don't just mean RDoc tags and such, but how to 
organize, how to write tutorials, how and when to write code examples, 
etc. Perhaps that could be part of your project as a Wiki?

I'm really looking forward to your project!


Best regards,

Jari Williamsson