I have been working on a CMS with ruby documentation, examples, and API. I
will show it soon. It is still incomplete. I will not release the address
until it is finished. --David Ross
···
-----------------------
dross [aT] code [dush] exec *at* net
-----------------------
Original Message:
-----------------
From: Randy Lawrence jm@zzzzzzzzzzzz.com
Date: Tue, 6 Jul 2004 11:13:59 +0900
To: ruby-talk@ruby-lang.org (ruby-talk ML)
Subject: Ruby Advocacy/Documentation/Sponsorship?
Having discovered Ruby recently and falling in love with it, I'm
wondering if there are any REMAINING reasons why Ruby isn't as
widespread as some of the older (less-productive) scripting languages.
Is there a perception that Ruby still lacks decent documentation?
Does lack of corporate backing hurt more than it helps?
Should RubyForge and RAA be merged into a single archive with an
interface similar to CPAN?
Is there a Ruby advocacy group?
I'm assuming the lack of English documentation was the major barrier
before 2002. IMHO, documentation now exists but they are scattered or
hard for newcomers to find (ie compared to Perl). A Ruby search engine
covering multiple websites would be really nice, starting with these
docs (maybe we can get a corporate sponsor to host the search engine):
....damn gotta run. At a minimum, maybe Ruby nuby's will hit this post
in Google and find it useful. Maybe someone else more qualified can hit
on the other topics like advocacy, etc.
--------------------------------------------------------------------
mail2web - Check your email from the web at http://mail2web.com/ .
Is there a perception that Ruby still lacks decent documentation?
I'm still having major problems with the documentation for ruby. For
example, I've been playing with WEBrick which is now integrated as
standard in Ruby. You would expect such a package to have to be at
least nearly completely documented. Well... have a browse
(http://www.ruby-doc.org/stdlib/libdoc/webrick/rdoc/index.html\). I
keep finding myself looking at bits of the source to try to figure out
what a method is for and if it's the one I'm actually looking for.
This can get especially tedious as Ruby isn't strongly typed so you
need to write code to figure out the class of a returned variable and
track all this in your mind etc... (If I'm being stupid here please
point it out to me! :)).
It just seems to me that this goes totally against the OO design and
advantages of ruby. I know the subject of documentation keeps coming
up here and we like to believe (icluding me) that it's an issue that's
been mostly resolved... but if we really look at how much is missing
from the standard libraries I believe we need to face some facts. If
nothing is done ruby can never live up to it's full potential.
In a bid to not simply complain... (cause we all hate those right ?) I
would have one suggestion. Why don't we make an application so that
people can submit documentation. I believe this is what MonoDoc does
for the Mono project where they have a GUI and a web-based interface
(http://www.mono-project.com/contributing/classlib-doc.html\). That way
each time someone plays around with an object or a method they can
just submit some documentation with a short sample of code. With such
a system, and participation of course, the documentation problem could
taken care very quickly.
Has anyone started such a project for ruby before ? Are there any
gotchas ? I would certainly be interested in giving my time on such a
project... are others interested ?
Daniel
P.S. regarding above, that was not a stab aimed particulary at WEBrick
which is an excellent addition to ruby for which I would like to add
my personal thanks
well, this would be nice, indeed.. A simple web form would fit imo..
···
il 6 Jul 2004 04:35:54 -0700, daniel@danielcremer.com (Daniel Cremer) ha scritto::
In a bid to not simply complain... (cause we all hate those right ?) I
would have one suggestion. Why don't we make an application so that
people can submit documentation. I believe this is what MonoDoc does
for the Mono project where they have a GUI and a web-based interface
(http://www.mono-project.com/contributing/classlib-doc.html\). That way
each time someone plays around with an object or a method they can
just submit some documentation with a short sample of code. With such
a system, and participation of course, the documentation problem could
taken care very quickly.
In a bid to not simply complain... (cause we all hate those right ?) I
would have one suggestion. Why don't we make an application so that
people can submit documentation. I believe this is what MonoDoc does
for the Mono project where they have a GUI and a web-based interface
(http://www.mono-project.com/contributing/classlib-doc.html\). That way
each time someone plays around with an object or a method they can
just submit some documentation with a short sample of code. With such
a system, and participation of course, the documentation problem could
taken care very quickly.
Maybe. It requires folks to take the time to actually write the docs, and time and effort to verify these docs for correctness.
well, this would be nice, indeed.. A simple web form would fit imo..
Or a Wiki. Or E-mail. Right now, people can, and a few people do, add documentation and examples to the Ruby Garden wiki. Or send documents or links to me for inclusion on ruby-doc.org. But not enough.
(I tried to take a look at the monodoc app, but the web version returns an error right off the bat, and the GTK version does not seem to get installed with the Windows version of mono 1.0.)
Perhaps making it even easier than it already is will help. I suspect, though, that most docs, like most code, gets written by a relatively small percentage of the user base.
James Britt
jbritt AT ruby-doc DOT org
···
il 6 Jul 2004 04:35:54 -0700, daniel@danielcremer.com (Daniel Cremer) > ha scritto::