From: JamesBritt <james@...>
Date: 2002-08-31T15:23:21+09:00
Subject: RE: suggestions to the Ruby community

>
> >I feel that in my original post i was specific as i could be. If people
> >here feel that the the overall online english ruby documentation does not
> >need improvement, great.
>
> All you've said is that the online docs for "modules and methods" was not
> complete or thorough - Personally, I think the online Pickaxe book is as
> good as any book for any other language in it's descriptions of the
> various built-in classes, modules and methods in the Ruby library.
>
> So I'll try one more time: Can you give us a _specific_ example where you
> found that you needed more information or the information wasn't clear?
> For example, you could say: "The explanation of the foo method in the
> module Fooable didn't tell me anything about how instance
> variables of the
> class it is being mixed into will be affected".


If somebody from the "outside" (for lack of a better word) makes a comment
or an observation, those on the "inside" should consider that, all possible
explanations/refutations/rationalizations aside, that *is* how things appear
to at least one, and probably more, outsider.

Clearly, somebody has a problem locating and using Ruby documentation.

One issue, if I'm reading this right, is that there is no one single place a
developer may go to look for complete documentation on all Ruby classes,
libs and modules.  This is a valid concern.  The Pick-Axe book covers a lot
of ground, but does not include documentation for every standard library.
For example, I recently needed to understand monitor.rb.  Searching the
WinHelp version of the Pick-Axe turned up nothing. The paper version doesn't
list it in the index.

The source code has some sparse RD doc, but it does not *explain* the module
or its methods, giving only a rather sparse example.  Besides, if you're new
to Ruby, you need to know what the RD doc format is, and know to go install
rdtool to see it as formatted output.  (Oddly, it does not come as part of
the standard installation, even though so much source uses RD.)

ri tells me, "Couldn't find class/module `MonitorMixin'."

Searching the ruby-talk archives doesn't give any doc pointers, either. The
Ruby Developer's Guide book doesn't list monitor.rb in the index; neither
does Ruby in 21 Days.  The Ruby Way has an entry for monitoring, and turning
to page 378 I see it discusses monitor.rb.  OK, so I can read the
description and look over the example.  It's helpful, but, in the end, I
don't think it's quite accurate to say monitor.rb is *documented* in The
Ruby Way.

This isn't an isolated case, just one that's fresh in my mind.  And it isn't
meant as a slam on anybody who's taken the time and effort to contribute to
Ruby development.   Not to single out Ruby or any developers, I have a
problem in general with much open-source software and the almost universal
lack of even cursory documentation.  (About the only good thing about it is
that it offers opportunities for industrious book writers.)

Now, there can be any number of explanations for this.  An obvious one is
that many Ruby developers are not native English speakers. Another reason,
common to pretty much all development, is that developers just don't like to
write documentation.   (When called on this, many simply tell you to read
the source code, as if dismantling a bike will tell you how to ride one.)
Sometimes it's just a matter of time; writing  free software as part of a
busy life doesn't leave much opportunity for certain niceties.

Ideally, when somebody asks about documentation for such-and-such, we should
be able to say, "try http://some.example.com/docs/such-and-such", much as
you can do with PHP.  We could perhaps start an Adopt a Library program, and
see to it that every bit of Ruby is documented in *one* place, with a
simple, uniform means of access.

One should also be able to run RDoc or rdtool on the Ruby source tree, and
get reasonable documentation for every class and module.

(By "reasonable documentation" I mean class and module names, a list of
methods and parameters, what the parameters are supposed to be, what the
code is intended to do, circumstances for appropriate use, known problems,
version number, required files, and related classes and modules.)

There was a thread some time back about adding documentation to the 1.7 or
1.8 source, but I don't know what came of it.

In general, if somebody has a criticism of Ruby, and it takes more than one
succinct  sentence to refute the claim, then there's a problem.  (To quote
JC Watts, an American ex-politician, "If you have to explain, you've already
lost." )

We should not shoot the messenger, nor pick apart the comment, nor tell the
person the problem is with him or her.  Do not tell the person that, since
he or she has pointed out the problem, he or she should offer to head up a
project to fix it.  (Not to say these things have happened in this thread,
but they have happened at different times in the past.)

Documentation needs work, and we need a plan to improve it.
I would be happy to contribute.

Perhaps, as a start, we might get a list of all classes/modules, and find
out who owns each one.  See if the owner is willing and able to write any
needed documentation.  If not, start looking for somebody to take over that
documentation, and see if the code owner is at least available for
consultation when questions arise.

We would need a documentation repository (perhaps a wiki), agreement on what
the documentation should contain, and what formatting is used.

It would be nice, too, if at the end we had documentation in both Japanese
and English.


James