No documentation for modules on RubyForge?

[Aaron Becker]

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:
http://www.brainjar.com/dhtml/domviewer/ . 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

 

[Daniel Harple]

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

 

[Aaron Becker]

------=_Part_1945_137534.1141724991336
Content-Type: text/plain; charset=ISO-8859-1
Content-Transfer-Encoding: quoted-printable
Content-Disposition: inline

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 show=
s
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

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

-- Daniel

------=_Part_1945_137534.1141724991336--

 

[Geoff Lane]

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.

 

[Daniel Harple]

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

 

[James Edward Gray II]

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 Gray II

 

[Daniel Harple]

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

 

[ara.t.howard]

Don't expect me to be an expert Ruby programmer if I am new to the langua= ge.
But even the most level-headed developer would expect that all modules wo= uld
have documentation.

i would consider myself exetremely level headed and i disagree quite strong=
ly
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=3Dahoward

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 i=
t
helpful. they send bug reports, patches, and even docs to contribute. the
reality is that i __cannot__ spend the time to maintain encylopedic docs fo=
r
each project i release. i've found that a simple README and some samples w=
ill
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 you=
r
code and figure out what's happening - they shouldn't be using it. especia=
lly
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 g=
ood
samples. but, again, that's simply the most i have time for - it's very ti=
me
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=E2=80=99t someone write a simple webrick app to navigate the symbols = and
namespaces at run-time? Shoot, look at the JavaScript and DOM if you nee= d
an example of a possible interface: http://www.brainjar.com/dhtml/domview= er/
. And when I used Symbol.all_symbols it wasn=E2=80=99t 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 i=
t
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=
=2E

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=3Dcomp.lang.r=
uby&q=3Dcat+a.rb&qt_g=3D1&searchnow=3DSearch+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 enjoyab=
ly.
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 tha=
t
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-p=
lug
and spend some time with his daughter.

regards.

-a

--=20
judge your success by what you had to give up in order to get it.
- h.h. the 14th dali lama

 

[James Edward Gray II]

Warning: flames ahead...

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

My opinion is Ruby is doomed if it doesn't enforce some type of =20
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 =20
open source community, so we all need to be doing our part.

I've documented four standard libraries now and I run the Ruby Quiz, =20
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 =20
there is no process here.

You are welcome to post a Best Practices Gem Checklist, but you need =20
to keep in mind the two things you didn't when sending this message: =20=

we may not agree on all points and most people releasing Ruby =20
libraries are working for free.

Has anyone analyzed the most likely stumbling blocks for new =20
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 =20
remotely related.

Can=92t 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 =20=

say. Perhaps you have heard the phrase, "You can catch more flies =20
with honey?"

James Edward Gray II

 

[James Britt]

...
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 Quiz, 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.