From: Gavin Sinclair <gsinclair@...>
Date: 2004-02-02T10:14:17+09:00
Subject: Documentation approaches (was: Python 25 times as popular as Ruby !?)


[Charles Comstock:]
> I certainly would probably rather do it in C# then Java.  It's
> interesting in the 2.0 spec for C# they are adding yield symantics,
> anonymous method blocks and generics.  But the first two allow all the
> iteration style of Ruby that is so nice.  In terms of a typed language I
>  don't mind C# that much, it's alot more logical then Java.  I have many
>  bones to pick with Microsoft, but they did fix alot of the stupid
> problems in Java.  I think it's an acceptable language.

Thanks for the report.  C# sounds more interesting than it used to.  I
frequently hear from friends that it's a decent language, a tolerable
platform, and has awful (wait for it) documentation.

> [...]

> We definitely more complete docs on lots of things though, that is my
> main problem with Ruby.  There are lots of things I know I can do,
> without duplicating work, but since I can't find docs on it, it's
> difficult to do.  The push for RDoc is great, but I still have the same
> complaints about it that I have of Javadoc, it generally doesn't give
> some sort of example for each function, class in the library.  I learn
> far more from an example of code use that encompasses a wide part of the
>  library then a list of functions I can call in the library.  The 2nd is
>  great, but it only works if you know how to use it already.  Fix the
> documentation and I think ruby will certainly spring ahead.

I fully agree on all counts.  I'll just mention, though, that RDoc
actually encourages introductory/usage/example documentation, *so long as
the developer wants to write it*.  For example:

 * http://extensions.rubyforge.org/

The *first thing you see* (an important consideration for people looking
at an RDoc screen for the first time) is a description of the project,
installation, usage, technical information, links, etc.

 * http://www.ruby-doc.org/stdlib/libdoc/pathname/rdoc/index.html

Here, the first thing you see is a brief description of the 'pathname'
Ruby standard library.  It could use a one-paragraph description and usage
example to help the casual browser (person, not software) decide whether
they're interested.  However, the most important thing is the prominent
"For documentation, see class Pathname [linked]", which contains intro,
examples, and a method catalogue.

RDoc was certainly not a hinderance to creating decent documentation for
the 'pathname' library!

These examples serve as guidelines for me when creating new documentation.

Cheers,
Gavin