No documentation for modules on RubyForge?

Ruby
1

Warning: flames ahead…

My opinion is Ruby is doomed if it doesn’t enforce some type of quality
control on modules and general usability. This is especially true for
the gotchas new users will face.

Why not have a checklist of requirements for accepted modules? I used
gem to install “stomp” but there is no documentation and not even a
synopsis in the code.

Also the module loading error messages from Ruby are wanting.

Has anyone analyzed the most likely stumbling blocks for new users? Has
anyone done a usability study on new users?

There’s nothing worse than having potential and then not following
through with the fundamentals.

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.

The same goes for ‘reliable/msg’. It has no documentation. And it’s
claimed to be ‘stable’??? WTF?

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

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:
BrainJar.com: DOM Viewer . 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.

And where is a cookbook or snippet site for Ruby code? And what about
the ability to search Ruby-talk archives? Surely Google could help with
that.

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.

hackdaddy

2

On Mar 7, 2006, at 6:29 AM, Aaron Becker wrote:

The same goes for ‘reliable/msg’. It has no documentation. And it’s
claimed to be ‘stable’??? WTF?

Run gem_server to see documentation for installed gems. reliable-msg
looks well documented to me.

– Daniel

3

You’re right. There is documentation there.

However, none of the synopsis examples work on my machines. Nor are the
require statements shown at the top for the synopsis examples.

How about requiring sample code for all modules? It would be helpful to
have a complete working example to start with.

After working around a thread starvation issue with Ruby last week, I
think
I had a moment of pure frustration with the current state of Ruby. It
shows
great promise, but it’s frustrating to see little things tarnish it’s
potential.

I just started using Ruby in the past couple of weeks and I am very
impressed but also dismayed. Keep up the excellent work.

hackdaddy

4

Daniel H. wrote:

On Mar 7, 2006, at 6:29 AM, Aaron Becker wrote:

Run gem_server to see documentation for installed gems. reliable-msg
looks well documented to me.

– Daniel

Along these lines, I’ve always wondered why ‘ri’ could not be used for
all of the installed modules/gems, etc on the system. There are base
install classes (OptionParser, MD5, SOAP::WSDLDriverFactory for example)
that don’t show anything in ‘ri’. I think having one place to turn for
documentation is a good idea.

5

On Mar 7, 2006, at 2:27 PM, Geoff L. wrote:

Along these lines, I’ve always wondered why ‘ri’ could not be used
for all of the installed modules/gems, etc on the system. There are
base install classes (OptionParser, MD5, SOAP::WSDLDriverFactory
for example) that don’t show anything in ‘ri’. I think having one
place to turn for documentation is a good idea.

I believe a patch was submitted, and ‘ri’ documentation generation
will be included in the next release.

– Daniel

6

Aaron Becker wrote:

However, none of the synopsis examples work on my machines. Nor are the
require statements shown at the top for the synopsis examples.

You must require ‘rubygems’ first. This adds the gems to your
$LOAD_PATH. To have ruby automatically do this, set a shell variable
RUBYOPT="-r rubygems".

– Daniel

7

On Mar 7, 2006, at 7:27 AM, Geoff L. wrote:

Along these lines, I’ve always wondered why ‘ri’ could not be used
for all of the installed modules/gems, etc on the system. There are
base install classes (OptionParser, MD5, SOAP::WSDLDriverFactory
for example) that don’t show anything in ‘ri’. I think having one
place to turn for documentation is a good idea.

This is generally because those libraries are not yet documented. If
you get one figured out, please consider adding the documentation and
sending in a patch to Ruby Core.

James Edward G. II

8

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: BrainJar.com: DOM Viewer
. 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

9

James Edward G. II wrote:

…
What have you done to improve the new user experience? This is an open
source community, so we all need to be doing our part.

I’ve documented four standard libraries now and I run the Ruby Q., so
I’m sure trying to do mine.

I want to say “Thanks!” for what James has done, and continues to do,
and remind people that the barrier to entry is, for many things, quite
low. There are all sort of ways people can help improve Ruby and the
Ruby community, even if you are just starting out.

You do not need to write a full-featured application, nor author a
bestselling book, nor host and maintain a high-traffic Ruby site. There
are Ruby libraries whose docs need a review for accuracy, code that
needs even basic comments. One can document their experiences and offer
concrete suggestions on improvement, or publish notes on what they
learned. Put together a “Tips for Newbies” page. Read ruby-talk and
offer to answer questions, even if all one knows is basic stuff. (It’s a
good way to learn Ruby. Public exposure of ignorance is a great teacher.
Trust me on this; I know from experience.)

It seems their are people who believe that the Ruby community is a
well-funded, well-organized group of full-times Ruby uberlords, and that
sufficient griping will goad The Powers That Be into Making Things
Right.

The reality is that things happen in Ruby because people who might
otherwise have simply griped realized that they are The Powers That Be.

–
James B.

“A principle or axiom is of no value without the rules for applying it.”

  • Len Bullard
10

[email protected] writes:

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.

[…]

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.

Two words: Thank you!

11

On Mar 6, 2006, at 11:29 PM, Aaron Becker wrote:

Warning: flames ahead…

That’s disappointing. If you know you’re out of line, you could fix
it before you send the message.

My opinion is Ruby is doomed if it doesn’t enforce some type of
quality
control on modules and general usability. This is especially true for
the gotchas new users will face.

What have you done to improve the new user experience? This is an
open source community, so we all need to be doing our part.

I’ve documented four standard libraries now and I run the Ruby Q.,
so I’m sure trying to do mine.

Why not have a checklist of requirements for accepted modules? I used
gem to install “stomp” but there is no documentation and not even a
synopsis in the code.

Who said gems are “accepted modules?” Anyone can release gems, so
there is no process here.

You are welcome to post a Best Practices Gem Checklist, but you need
to keep in mind the two things you didn’t when sending this message:
we may not agree on all points and most people releasing Ruby
libraries are working for free.

Has anyone analyzed the most likely stumbling blocks for new
users? Has
anyone done a usability study on new users?

Will you be funding that?

The same goes for ‘reliable/msg’. It has no documentation. And it’s
claimed to be ‘stable’??? WTF?

Whether or not code is “stable” and has documentation are not
remotely related.

Can?t someone write a simple webrick app to navigate the symbols and
namespaces at run-time?

Sounds like you just found your first project to make Ruby better.

And where is a cookbook or snippet site for Ruby code?

http://www.oreilly.com/catalog/rubyckbk/index.html

And what about the ability to search Ruby-talk archives?

http://ruby-talk.org/ruby/ruby-talk/index.shtml

Surely Google could help with that.

Yes, you can do it that way too:

http://groups.google.com/group/comp.lang.ruby

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.

This was the absolute wrong way to win us over to anything you had to
say. Perhaps you have heard the phrase, “You can catch more flies
with honey?”

James Edward G. II

12

Geoff L. wrote:

that don’t show anything in ‘ri’. I think having one place to turn for
documentation is a good idea.

For “standard” Ruby, all I’ve ever needed is documentation for the core
and stdlib, which is covered entirely by www.ruby-doc.org (“thank you”
to the site maintainers and contributors!) and/or PickAxe.

As someone else already mentioned, when it comes to non-standard libs
(modules, gems), I think developers expect (should expect?) that
documentation and quality are a sort of “at your own risk” type of thing
– particularly with relatively young languages. Indeed, anyone can
release a gem on their own site or via rubyforge.org. I’m no Perl
veteran, but I suspect CPAN wasn’t that good in its earliest days, and
it took maybe a few years and a lot of community effort to mature into
what it is today.

I do agree that a centralized location for documentation is a good idea,
since it is what turned me onto Java years ago; I knew I could go to
java.sun.com’s documentation of the standard lib for reference, and
didn’t need to go elsewhere, except for examples and tutorials.

For now, ruby-doc.org serves me very very well.

13

On Tuesday 07 March 2006 09:16 am, [email protected] wrote:

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

I’ve attempted to write documentation for “products” which I’ve first
had to
learn from minimal or no documentation. It is very difficult, and by
the
time I’m done learning the product, I’m often frustrated at the prospect
of
trying to document it.

I’d suggest there has to be a better way–one possibility might be that,
if
the original programmer doesn’t have time to create written
documentation, he
take tape recorder in hand and document the program that way.
Interested
parties could obtain that tape (perhaps download a sound file via the
Internet?) and begin their documentation efforts from there.

This might save the developer some time, although it would be nice if he
remained available to answer questions and review draft documentation.

Randy K.