On Sunday 23 February 2003 10:53 am, Brian Wisti wrote:
> On Sunday 23 February 2003 09:18 am, Seth Kurtzberg wrote:
> > Another note:  for some key modules there is documentation only in
> > Japanese.
>
> This little sentence speaks volumes about one of the major challenges for
> Ruby.  The language is an international effort, with people contributing
> thoughts and ideas from all over the globe.  This is wonderful because oour
> enjoyment of Ruby gives us a common bond.  On the other hand, it is
> awkward, because the best documentation for one module is in Japanese,
> while another module's documentation is in English.  How much effort is
> being duplicated simply because we do not realize that somebody else
> already covered it in another language?

It is more than that.  I have just written a module that already exists, and I 
was always aware that Japanese documentation exists.  That doesn't help; if I 
can't find one of my Japanese speaking friends, knowing the documentation 
exists in Japanese doesn't help me.  (I also rewrote it because the other 
implementation is poorly designed, but that is a separate issue.)

The solution is straightforward, if perhaps annoying; simply don't accept any 
module as "official" Ruby unless the documentation is included.  Having a 
common format for the documentation would of course be very beneficial, but 
one step at a time.

>
> I would like to see a documentation browser in the style of Perldoc, but
> now I think that it would only address part of the issue.  Perhaps we can
> take a close look at how other successful projects have handled the
> challenges we are facing right now.  PHP and KDE are the first such
> projects that I think of, but I am sure there are others.
>
> 	- http://www.php.net/docs.php
> 	- http://i18n.kde.org/
>
> I have seen several attempts to tie all of the Ruby documentation together.
>  I am wondering how successful they are, and any ideas that they could
> contribute to this, or any help that they need.  It would be embarassing to
> duplicate effort when the goal is to reduce duplication :-)
>
> It is time to send this off and get more coffee before I start to ramble
> too much!
>
> -Brian W

-- 
Seth Kurtzberg
M. I. S. Corp.
480-661-1849
seth / cql.com