Re: suggestions to the Ruby community

In article <[e-mail]>,
stibbs  <[e-mail]> wrote:
>
>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".
>> <snip>
>>>
>> 
>> 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