Asp Forum - Ruby documentation.

Adam Fabian

12/3/2004 1:51:00 AM

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?
--
Adam Fabian (afabian@austin.rr.com)

30 Answers

dblack

12/3/2004 1:57:00 AM

David G. Andersen

12/3/2004 2:39:00 AM

On Fri, Dec 03, 2004 at 10:56:56AM +0900, David A. Black scribed:
> >
> > 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.ru.... 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

--
work: dga@lcs.mit.edu me: dga@pobox.com
MIT Laboratory for Computer Science http://www....

Nicholas Van Weerdenburg

12/3/2004 3:31:00 AM

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

Adam Fabian wrote:

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

JD

12/3/2004 4:02:00 AM

David G. Andersen wrote:
> 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.

T. Onoma

12/3/2004 6:06:00 AM

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.

Yuu

12/3/2004 10:19:00 AM

Nicholas Van Weerdenburg wrote:
> 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

12/3/2004 11:31:00 AM

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

12/3/2004 11:59:00 AM

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

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

--
Stefan

John Wilger

12/3/2004 2:20:00 PM

On Fri, 3 Dec 2004 20:59:25 +0900, Stefan Lang <langstefan@gmx.at> wrote:
> 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

12/3/2004 3:24:00 PM

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

comp.lang.ruby

Ruby documentation.