[lnkForumImage]
TotalShareware - Download Free Software

Confronta i prezzi di migliaia di prodotti.
Asp Forum
 Home | Login | Register | Search 


 

Forums >

comp.lang.ruby

No documentation for modules on RubyForge?

Aaron Becker

3/7/2006 5:29:00 AM


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/... . 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



--
Posted via http://www.ruby-....


12 Answers

Daniel Harple

3/7/2006 5:43:00 AM

0

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


Aaron Becker

3/7/2006 9:50:00 AM

0

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


On 3/6/06, Daniel Harple <dharple@generalconsumption.org> wrote:
>
> 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
>
>

Geoff Lane

3/7/2006 1:27:00 PM

0

Daniel Harple 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.


Daniel Harple

3/7/2006 1:39:00 PM

0

On Mar 7, 2006, at 2:27 PM, Geoff Lane 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


James Gray

3/7/2006 1:44:00 PM

0

On Mar 7, 2006, at 7:27 AM, Geoff Lane wrote:

> Daniel Harple 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.

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

3/7/2006 1:50:00 PM

0

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

--
Posted via http://www.ruby-....


Ara.T.Howard

3/7/2006 2:17:00 PM

0

James Gray

3/7/2006 2:48:00 PM

0

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

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

http://ruby-talk.org/ruby/ruby-talk/i...

> Surely Google could help with that.

Yes, you can do it that way too:

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

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



james_b

3/7/2006 3:51:00 PM

0

James Edward Gray 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 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.


--
James Britt

"A principle or axiom is of no value without the rules for applying it."
- Len Bullard


Christian Neukirchen

3/7/2006 6:02:00 PM

0

ara.t.howard@noaa.gov writes:

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

[...]

> 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!

--
Christian Neukirchen <chneukirchen@gmail.com> http://chneuk...