From: ara.t.howard@...
Date: 2006-03-07T23:16:48+09:00
Subject: Re: No documentation for modules on RubyForge?

On Tue, 7 Mar 2006, Aaron Becker wrote:

> Don't expect me to be an expert Ruby programmer if I am new to the language.
> But even the most level-headed developer would expect that all modules would
> have documentation.

i would consider myself exetremely level headed and i disagree quite strongly
here.  consider : i maintain about 40 open source libraries

   http://codeforpeople.com/lib/ruby/
   http://rubyforge.org/projects/codeforpeople/
   http://raa.ruby-lang.org/search.rhtml?search=ahoward

i also 'maintain' a 50-60 hr/wk job.  a wife.  a kid.  a totally dyi house
remodel.  and three border collies that must go either running, skiing, or
mountain biking every single day.

i release my code because i hope people will find it useful.  often i'll
release something as soon as it's reusable and discover noboby finds it
interesting!  other times i release something and quite a few people find it
helpful.  they send bug reports, patches, and even docs to contribute.  the
reality is that i __cannot__ spend the time to maintain encylopedic docs for
each project i release.  i've found that a simple README and some samples will
suffice for 80% of the ruby developers out there.  if a project is really
useful my hope is that those developers can answer questions for the other
20%, or, even better contribute to doccumenting the project.  i don't even
bother with rdoc any more.  know why?  because if developers can't read your
code and figure out what's happening - they shouldn't be using it.  especially
with a language as concise as ruby.  the same doesn't hold for how it's
expected to be used - so i make a concession by writing a README and some good
samples.  but, again, that's simply the most i have time for - it's very time
consuming to release code - with or without documentation.

> Besides Ruby is so powerful, I can't believe that anyone hasn't improved
> these fundamentals.  I've never had this issue with CPAN.

and i've never had it with ruby...

> Can’t someone write a simple webrick app to navigate the symbols and
> namespaces at run-time?  Shoot, look at the JavaScript and DOM if you need
> an example of a possible interface: http://www.brainjar.com/dhtml/domviewer/
> .   And when I used Symbol.all_symbols it wasn’t clear how to get the full
> namespace of the symbols.  Navigating the symbols in Perl is far easier.

i think the word 'simple webrick app' isn't the best description here - if it
is you could certainly write it yourself right?  it's astounding how hard it
is to write something that one can give away and have people find useful.  if
you want them to find it useful on a variety of platforms it's harder still.


> And what about the ability to search Ruby-talk archives?  Surely Google
> could help with that.

i'm using google to do it right now.  i found quite a few snippets:

   http://groups.google.com/group/comp.lang.ruby/search?group=comp.lang.ruby&q=cat+a.rb&qt_g=1&searchnow=Search+this+group

seriously, i find the google interface extremely useful for finding code
snippets and use it almost daily for exactly this - in fact it's the only
reason i use it over my news reader.


> You can spray a dog turd with gold paint, but it's still a dog turd.
> Hopefully, you can make Ruby live up to the hype...  And soon.

i, for one, have absolutely no need to make ruby live up to any hype.  why
should anyone?  ruby helps me get my job done more quickly and more enjoyably.
i contribute back to the community because the community has helped me many
times.  i'm certainly not selling my software and neither is matz - there
really isn't that much to be gained by making it live up to anything other
than what it is.

consider this, by the time this thread dies out there will have been enough
words slung and time spent to doccument at least three built-in classes and to
send the improved docs to ruby-core.  matz is very good about accepting
contributed docs and merging them into the core.  my guess, however, is that
people would rather write about docs that to actually write docs and anyone
(including myself) who responds to this thread is certainly guilty of that.

anyhow - i hope you realize that i'm not trying to yank your cord - it just
seems to me that the open source world is full of very busy people working
extremely hard and then giving that work away, and that it's reasonable to
expect the rest of us to pitch in when it comes to writing docs so that
anonymous guy that saved you a week on the other side of the world can un-plug
and spend some time with his daughter.

regards.

-a

-- 
judge your success by what you had to give up in order to get it.
- h.h. the 14th dali lama