Ruby documentation.

[Adam Fabian]

I'm kind of getting the impression that Ruby might not be
well-documented in English. I'm looking for a primary language to
pick up as a hobby (with, perhaps, as a bonus, some modicum of useful
applicability for the system administration I do), and from what I've
read of Programming Ruby online, I really like the syntax and design
and everything. On the other hand, I'm a sucker for good
documentation. Perl's syntax is frankly, in my humble opinion, ugly
and inscrutable, but it's certainly well-documented!

So, what's the Ruby experience like for a native English speaker with
no knowledge of Japanese and no inclination to read the Ruby source to
figure out how things work?

 

[David A. Black]

Hi --

I'm kind of getting the impression that Ruby might not be
well-documented in English. I'm looking for a primary language to
pick up as a hobby (with, perhaps, as a bonus, some modicum of useful
applicability for the system administration I do), and from what I've
read of Programming Ruby online, I really like the syntax and design
and everything. On the other hand, I'm a sucker for good
documentation. Perl's syntax is frankly, in my humble opinion, ugly
and inscrutable, but it's certainly well-documented!

So, what's the Ruby experience like for a native English speaker with
no knowledge of Japanese and no inclination to read the Ruby source to
figure out how things work?

Welcome to Ruby

Documentation in some areas is uneven, but you should have no trouble
learning and using and enjoying the language. A very good starting
point is http://www.ruby-doc.org. Also, don't forget that you can
come over to the Ruby IRC channel (#ruby-lang on irc.freenode.net) for
real-time documentation


David

 

[David G. Andersen]

Welcome to Ruby

Documentation in some areas is uneven, but you should have no trouble
learning and using and enjoying the language. A very good starting
point is http://www.ruby-doc.org. Also, don't forget that you can
come over to the Ruby IRC channel (#ruby-lang on irc.freenode.net) for
real-time documentation

Buy/rent/borrow/beg the pickaxe book. The class reference at the end is
astoundingly useful. Go for the 2nd edition if you have a choice,
since it covers 1.8.

-Dave

 

[Nicholas Van Weerdenburg]

Hi Adam,

I think that may have been the case a few years ago, but I don't think
it applies much now. English documentation is pretty good, especially
for some of the core libraries people have developed. I only started
using Ruby six months ago, and have had no real issue with finding
documentation. The only issue might be some less common libraries, but
that doesn't really effect the core usage of Ruby for day-to-day.

There are also some great books- almost all of them on Amazon are good,
with "Programming Ruby 2nd Edition" by Dave Thomas and Andy Hunt and
"The Ruby Way" by Hal Fulton being particularly good. "Ruby Developer's
Guide" is also good, and takes a different tack then the other two (all
three are quit different in style and approach).

And the community is awesome and very active. There are 50+ messages a
day on this newsgroup, and a good portion of it is pretty deep by very
knowledgeable people. One good side effect of the news group is that it
raises the bar of how you define talent.

Nick

 

[J. D.]

On Fri, Dec 03, 2004 at 10:56:56AM +0900, David A. Black scribed:

Buy/rent/borrow/beg the pickaxe book. The class reference at the end is
astoundingly useful. Go for the 2nd edition if you have a choice,
since it covers 1.8.

-Dave

I have a hardcopy of pickaxe 2nd edition (by Dave Thomas) and think it
is one of the best books covering a programming language.

IMHO, the freely available pickaxe book 1st edition is somewhat
overrated while the pickaxe book 2nd edition is underrated. Maybe I'm
biased because I didn't start using Ruby until 1.8.

Is there an up-to-date comp.lang.ruby FAQ that mentions all the online
docs? Maybe it should be automatically posted to this newsgroup on a
weekly or monthly basis.

 

[trans. (T. Onoma)]

On Thursday 02 December 2004 11:07 pm, J. D. wrote:
| I have a hardcopy of pickaxe 2nd edition (by Dave Thomas) and think it
| is one of the best books covering a programming language.
|
| IMHO, the freely available pickaxe book 1st edition is somewhat
| overrated while the pickaxe book 2nd edition is underrated. Maybe I'm
| biased because I didn't start using Ruby until 1.8.

For Ruby 2 and Pickaxe III, I'd really like to see a high quality Hardback
special edition!

T.

 

[Iwan van der Kleyn]

I think that may have been the case a few years ago,

Although that may be true, I think that the present state of Ruby's
documentation is far from ideal. Newbies (like me) do not compare the
present state of affairs with how it used to be but compare it with the
availability and quality of documentation with Perl or Python. And both
languages are far superior in this respect.

Don't get me wrong. I've been busy with Ruby for a few weeks now. I like
the language and think the implementation is superb. The pickaxe book is
indeed excellent. On par with Learning Python (with better practical
examples) and probably a bit better than Learning Perl.

However, the reference documentation is of "irregular" quality at best.
The soap or socket modules are good examples. They are not documented at
all. For me these modules are not "less common"...

This is not to troll by the way. If I decide to stick around with Ruby
I;ll probably do my bit to help. But I do think that it's an issue
which should be taken seriously.

 

[gabriele renzi]

Iwan van der Kleyn ha scritto:

However, the reference documentation is of "irregular" quality at best.
The soap or socket modules are good examples. They are not documented at
all. For me these modules are not "less common"...

about the Socket stuff. I always wondered why there was documentation
about BasicSocket, Socket, TCPSocket and so on since the first version
of the pickaxe, but it never flew into ri. Is it just the lack of
someone contributing a doumentation patch ?

 

[Stefan Lang]

Am Freitag, 3. Dezember 2004 02:50 schrieb Adam Fabian:

I'm kind of getting the impression that Ruby might not be
well-documented in English. I'm looking for a primary language to
pick up as a hobby (with, perhaps, as a bonus, some modicum of useful
applicability for the system administration I do), and from what I've
read of Programming Ruby online, I really like the syntax and design
and everything. On the other hand, I'm a sucker for good
documentation. Perl's syntax is frankly, in my humble opinion, ugly
and inscrutable, but it's certainly well-documented!

I have got books for Perl in English and German (my native language) but
it took me at about one month to understand most of Perl's syntax,
built-in operators, file handling etc.
And even now, I often have to look up documentation because
I can't remember exactly how I have to dereference correctly
a hash(ref) in an hash in an array......

I startet learning Ruby about 10 days ago and I must admit,
I am faster in writing Ruby code than Perl code, make less
mistakes and I also understand more Ruby code written by others
than Perl code.

I started with the online version of the "Pragmatic Programmer's Guide":
http://www.rubycentral.com/book/

So, what's the Ruby experience like for a native English speaker with
no knowledge of Japanese and no inclination to read the Ruby source to
figure out how things work?

See above. My native language is German, but I learned only from
English docs.

Documentation of some standard modules could be better, like e.g. REXML,
but perhaps I haven't looked at the right places for it...

 

[John Wilger]

Documentation of some standard modules could be better, like e.g. REXML,
but perhaps I haven't looked at the right places for it...

Of course, one of the great things about Ruby is that---after you have
grepped the basic syntax---when documentation is lacking, the source
code is generally easy enough to understand that you don't really need
the documentation anyway. Granted, this doesn't mean that we don't
need more/better docs on a lot of the code out there, but it speaks
volumes about the beauty of the Ruby language itself.

Also, I've found that (when I can't find "official" documentation)
simply running RDoc over a module is a good place to start. Depending
on how well the code is commented, you might not get a lot of
examples/usage instructions, but it does make a handy way to quickly
browse the source code and see what is related to what.

--
Regards,
John Wilger

-----------
Alice came to a fork in the road. "Which road do I take?" she asked.
"Where do you want to go?" responded the Cheshire cat.
"I don't know," Alice answered.
"Then," said the cat, "it doesn't matter."
- Lewis Carrol, Alice in Wonderland

 

[Cameron McBride]

Just hitting the obvious points that have been discussed before:

documentation is far from ideal. Newbies (like me) do not compare the
present state of affairs with how it used to be but compare it with the
availability and quality of documentation with Perl or Python. And both
languages are far superior in this respect.

It is good to realize ruby docs are not on the same level as perl or
python, but that
shouldn't surprise anyone. Those other communities are larger, and
have been more active (at least in English based usage and discussion)
for more years. They also carry the other respective boons and banes
of a larger community.

On the other hand, it's also good to realize the comparison is
partially flawed. In a Karate class, you don't say a 14 yr old has
better technique than an 8 yr old just cause the former can kick the
stuffing out of the latter.

To address Iwan directly, not all documentation is 'ideal' but I
would definately classify most as usable. And the fact that this has
changed dramatically in the past couple of years means the ball is
rolling and it is going to get better. (sidenote: sincere thanks to
those that have made this reality. I might just be a lurker and minor
user, but man - it is *so* appreciated)

Adam, like others have mentioned - the basics are pretty well
explained. You might hit a snag with a library or module here or
there, but the general concensus is that if you post a "wtf is ...?"
to the mailing list, you'll get a decent reply rather than an RTFM.
So it's really a question of what you want.

FWIW, I thought ruby was worth learning back in 2001 when the docs
weren't to the current level and I don't read /speak a lick of
Japanese.

Oh, and Iwan: documentation is taken VERY seriously here, no worries.

Cameron

 

[Nicholas Van Weerdenburg]

Although that may be true, I think that the present state of Ruby's
documentation is far from ideal. Newbies (like me) do not compare the
present state of affairs with how it used to be but compare it with
the availability and quality of documentation with Perl or Python. And
both languages are far superior in this respect.

Don't get me wrong. I've been busy with Ruby for a few weeks now. I
like the language and think the implementation is superb. The pickaxe
book is indeed excellent. On par with Learning Python (with better
practical examples) and probably a bit better than Learning Perl.

However, the reference documentation is of "irregular" quality at
best. The soap or socket modules are good examples. They are not
documented at all. For me these modules are not "less common"...

This is not to troll by the way. If I decide to stick around with Ruby
I;ll probably do my bit to help. But I do think that it's an issue
which should be taken seriously.

Those are good points, and important ones.

I think there is a serious commitment, and it's taken very seriously.
I've been using Ruby for about six months now, lurking for ten, and
haven't lamented the documentation. But that many be because I haven't
used some of the libraries that suffer from a lack of documentation. I
also collected most of the Ruby books out there, and collected a lot of
sample code.

Also- look for the 1.9 online documentation- my understanding is that
it's had a lot added due to the generosity of the Pickaxe authors and
the team who updated the docs.

I do come from a C/C++/Java background, so it did take some time to
adjust to the new paradigms. But that wasn't due to a lack of documentation.

There also is a lot of effort going on in the area- to the point that
the Ruby community is obsessed with documentation. I think it's a bit
self-concious due to the years without. I expect that this is a good
thing, since it promises more rapid growth in documentation.

Also- look for the 1.9 online documentation- my understanding is that
it's had a lot added due to the generosity of the Pickaxe authors and
the team who updated the docs.

http://www.ruby-doc.org/stdlib/

Also, the sidebar plugin for FireFox is cool:
http://www.ruby-doc.org/docbar/

On that note, I'm still not exactly sure what the difference is between
the latest 1.9 docs and 1.8.1. If someone could give a definitive
clarification, that would be great.

Regards,
Nick

 

[Nicholas Van Weerdenburg]

Have you seen:

Home page for rexml:
http://www.germane-software.com/software/rexml/

Tutorial:
http://www.germane-software.com/software/rexml/docs/tutorial.html

Regards,
Nick

 

[James Britt]

Just hitting the obvious points that have been discussed before:




It is good to realize ruby docs are not on the same level as perl or
python, but that
shouldn't surprise anyone. Those other communities are larger, and
have been more active (at least in English based usage and discussion)
for more years. They also carry the other respective boons and banes
of a larger community.

On the other hand, it's also good to realize the comparison is
partially flawed. In a Karate class, you don't say a 14 yr old has
better technique than an 8 yr old just cause the former can kick the
stuffing out of the latter.

This sort of hand waving does more harm than good. Rationalizing the
state of a language by citing its lack of maturity just feeds the idea
that Ruby is not yet ready for prime time.

The comparison to Perl and Python is not flawed if people want to hold
up Ruby as equal or better. The available documentation either is or is
not acceptable; different people have different needs and criteria, but
no one is served by making excuses.

To address Iwan directly, not all documentation is 'ideal' but I
would definately classify most as usable. And the fact that this has
changed dramatically in the past couple of years means the ball is
rolling and it is going to get better. (sidenote: sincere thanks to
those that have made this reality. I might just be a lurker and minor
user, but man - it is *so* appreciated)

As are words of thanks to those who have been building up the available
bundled and online documentation resources. Thank you.

Adam, like others have mentioned - the basics are pretty well
explained. You might hit a snag with a library or module here or
there, but the general concensus is that if you post a "wtf is ...?"
to the mailing list, you'll get a decent reply rather than an RTFM.
So it's really a question of what you want.

FWIW, I thought ruby was worth learning back in 2001 when the docs
weren't to the current level and I don't read /speak a lick of
Japanese.

Oh, and Iwan: documentation is taken VERY seriously here, no worries.

Well, up to a point. I would at least take out the word 'very'; there
is still an overwhelming emphasis on code. Some have outstanding
documentation, while others have barely a README.

But maybe that's just the best use of resources.


James

 

[James Britt]

...

Those are good points, and important ones.
I think there is a serious commitment, and it's taken very seriously.
I've been using Ruby for about six months now, lurking for ten, and
haven't lamented the documentation. But that many be because I haven't
used some of the libraries that suffer from a lack of documentation. I
also collected most of the Ruby books out there, and collected a lot of
sample code.

Also- look for the 1.9 online documentation- my understanding is that
it's had a lot added due to the generosity of the Pickaxe authors and
the team who updated the docs.

I'm pretty sure that any new source code documentation has been going
into the 1.8.2 source; any way, that's what's being displayed at

http://www.ruby-doc.org/core/
and
http://www.ruby-doc.org/stdlib/

(I would think, though, that applicable docs would also go into the 1.9
tree.)

The 1.9 docs had been onlne, too, at one point, but have been taken
down; I wasn't keeping up with the changes, and it seemed of far less
general value then the other docs.

I do come from a C/C++/Java background, so it did take some time to
adjust to the new paradigms. But that wasn't due to a lack of
documentation.

It is a credit to Ruby's design that one can get a grasp of the
essential principles and syntax without having to keep track of too many
exceptions. So, for example, you can initially assume that everything
is an object, or that every method returns the value of the last
expression executed, and later on worry about the exceptions to these
things.

But that is of limited value when you get down to specific libraries and
you just have to know the API.

There also is a lot of effort going on in the area- to the point that
the Ruby community is obsessed with documentation. I think it's a bit
self-concious due to the years without. I expect that this is a good
thing, since it promises more rapid growth in documentation.

I'd really like to think this was true, but I just don't see it.
Obsessed? There may be some who rant about it more than others, but I
think, overall, you hear far more about new libraries and frameworks
than about documentation. Activity on the ruby-doc list is quite low; I
believe many original members have simply dropped out. I think we're on
the verge of becoming a secret cult.

Also- look for the 1.9 online documentation- my understanding is that
it's had a lot added due to the generosity of the Pickaxe authors and
the team who updated the docs.

http://www.ruby-doc.org/stdlib/

These are 1.8.2 docs, and I believe the bulk of the additions and
updates have been coming from the members of the Ruby Documentation
Project, plus the library developers themselves.

"The documentation itself has been created by Gavin Sinclair, William
Webber, Lyle Johnson, and library authors. Individual library files
usually have code and documentation credits."

On that note, I'm still not exactly sure what the difference is between
the latest 1.9 docs and 1.8.1. If someone could give a definitive
clarification, that would be great.

Well, I think what you are referring to as the 1.9 docs are in fact the
1.8.2 docs


James Britt
www.ruby-doc.org

 

[Cameron McBride]

Heyo,

This sort of hand waving does more harm than good. Rationalizing the
state of a language by citing its lack of maturity just feeds the idea
that Ruby is not yet ready for prime time.

not really, imo. I guess my point was that they were different.
Direct comparisons are always somewhat flawed and biased and so I was
trying to endorse examining if ruby had enough of what one needed,
rather than comparing.

Sorry to be confusing. To clarify my view (whatever that's worth), it
does seem that ruby is in prime time. The language itself isn't new,
but I'd say the push on english docs is relatively new, as the
situation has changed significantly in last couple of years.

The comparison to Perl and Python is not flawed if people want to hold
up Ruby as equal or better.

I'm pretty sure I said 'partially flawed', but your point is a good one.

The available documentation either is or is not acceptable; different people
have different needs and criteria,

Right, and the message I was trying to convey is that 'I find it
acceptable and it's getting better'

but no one is served by making excuses.

Didn't mean to be, nor would I dare. ruby rocks. It needs none.
Again, sorry for the confusion.

Cameron

 

[James Britt]

Right, and the message I was trying to convey is that 'I find it
acceptable and it's getting better'




Didn't mean to be, nor would I dare. ruby rocks. It needs none.
Again, sorry for the confusion.

And I'm sorry if I came off as harsh or dismissive. I think I was
having flashbacks to similar discussions some years ago, when someone
posted a serious criticism of the state of ruby documentation, and there
was a steady stream of, "Yes, but ..." answers, each trying to
rationalize or explain away the issue.

The situation has improved immensely, and though there is still much
more to be done, all involved should be quite proud of their work.


James

 

[Eric Hodel]

I'm kind of getting the impression that Ruby might not be
well-documented in English.

The less commonly used a particular library is used, the less likely it
is to be documented. DRb, Rinda and the thread synchronization classes
(like Queue or SizedQueue) are less well-documented than the standard
library and commonly used libraries like Net::HTTP.

 

[James Edward Gray II]

The less commonly used a particular library is used, the less likely
it is to be documented. DRb, Rinda and the thread synchronization
classes (like Queue or SizedQueue) are less well-documented than the
standard library and commonly used libraries like Net::HTTP.

I'm not sure how well that theory holds up. abbrev is documented, but
rexml and webrick are not yet well covered.

James Edward Gray II

 

[James Britt]

The less commonly used a particular library is used, the less likely it
is to be documented. DRb, Rinda and the thread synchronization classes
(like Queue or SizedQueue) are less well-documented than the standard
library and commonly used libraries like Net::HTTP.

Ah, but in such cases, stout souls do step froward:

http://segment7.net/projects/ruby/drb/index.html



Thanks Eric.


James