In article pan.2002.07.31.23.56.23.344521.11118@nothanks.foo,
In my original post i thought i made it clear that i am referring to the
overall online english documentation for modules/methods and ruby in
general (since that is what i specifically stated in my original post). I
don’t want to get side tracked or off topic on what seems to be a not so
pleasant subject for discussion in this newsgroup. Personally, books would
be a second concern for me until the online english documentation got up
to par organizationally and with the thoroughness and clarity of
python.org’s documentation. This is something the community as a whole can
take part in, where as compared to a book which is usually dictated by one
person or a very small handful of people.
I was just trying to give an inside look at one companies decision dealing
with Ruby. I also happened to mention on a personal note that i know
people that have tried ruby and even though they liked it a lot, they
all eventually made the decision to go back with their prior scripting
language within a few weeks with their reason being an overall lack of
clear and thorough (english) documentation.
So, i got up the balls and decided to make the post just to make sure
people in the community realized that people and possibly companies who
would otherwise be adopting ruby are not due to the english documentation
issue.
If the community already realized this issue to the same extent that i
have observed, I apologize for my original post.
Most, if not all, of Ruby’s built-in modules are documented in
“Programming Ruby”.
So again, could you give us some specific examples of actual
I feel that in my original post i was specific as i could be. If people
here feel that the the overall online english ruby documentation does not
need improvement, great.
All you’ve said is that the online docs for “modules and methods” was not
complete or thorough - Personally, I think the online Pickaxe book is as
good as any book for any other language in it’s descriptions of the
various built-in classes, modules and methods in the Ruby library.
So I’ll try one more time: Can you give us a specific example where you
found that you needed more information or the information wasn’t clear?
For example, you could say: “The explanation of the foo method in the
module Fooable didn’t tell me anything about how instance variables of the
class it is being mixed into will be affected”.
Again, I ask this because the various Ruby documentation out there (the
PickAxe book and online version, Ruby In a Nutshell, The Ruby Way, etc)
all seem to offer a very complete, thorough treatment of the language and
it’s libraries so I really don’t understand your statement about
documentation being incomplete or unclear. Now, perhaps, since I’ve been
using Ruby for a couple of years now and I was used to digging a little
deeper on my own for information before all this wonderful documentation
was available, I don’t see what the problem is now that
documentation seems to be readily available. By way of analogy, if I’ve
always had to walk to get anywhere and someone gives me a bicycle and
then sometime later someone with a car comes a long and says “Hey, your
mode of transportation isn’t as good as it could be, get a car!” I’m
likely to answer “What do you mean, I’m getting around great on this
bike!”. So since you were kind enough to point out an apparent lack
of documentation and want to enlighten us and help out the community it
would be helpful if you could give us a few specific examples of where
you felt the docs were lacking, cases where you and your colleagues were
scratching your heads wondering how you would actually use some class or
or method (and it actually kept you from getting anything done).
No personal attack on you is intended. Look at it this way, you said
in an earlier post that you have an open source project. I suppose that
your project includes docs for how to build, install and use your code.
If someone sent you an email that said: “Dude, I think your program is
great, but your docs suck!” and you asked for some specifics and all you
got back is: “Dude, the docs for how to use your system are lacking and
I’m gonna use a different program because of it.” wouldn’t you find that
a wee bit frustrating?
Phil
···
stibbs stibbs@nothanks.foo wrote:
