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?
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
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?
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.
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...
···
Am Freitag, 3. Dezember 2004 02:50 schrieb Adam Fabian:
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.
···
On 02 Dec 2004, at 17:50, Adam Fabian wrote:
I'm kind of getting the impression that Ruby might not be
well-documented in English.
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.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
···
--
work: dga@lcs.mit.edu me: dga@pobox.com
MIT Laboratory for Computer Science http://www.angio.net/
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.
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.
···
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...
--
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
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.
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...
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
···
On Dec 3, 2004, at 4:20 PM, Eric Hodel wrote:
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 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.
Ah, but in such cases, stout souls do step froward:
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.
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 ?
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.
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.
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.
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.
For Ruby 2 and Pickaxe III, I'd really like to see a high quality Hardback
special edition!
T.
···
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.
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.
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.
...
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'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
(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.
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
That's about it. Be careful though--some stuff has changed in socket since PA1
Cheers
Dave
···
On Dec 3, 2004, at 5:32, gabriele renzi wrote:
bout 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 ?
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.
