Re: suggestions to the Ruby community

On Fri, 30 Aug 2002 20:48:02 -0400, Phil Tomson wrote:

> 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
 
I personally use Ruby as my main scripting language and feel that Dave's
book is priceless. Maybe my original post was just a big mistake :). I was
basically just doing a dump of what one company thought when looking into
using ruby as a tool and also what i have seen some online friends pass
through pertaining to using ruby.

Please understand that the only reason we even considered using ruby at
work was because I brought it up often in conversations with coworkers
lately. When my coworkers and project manager presented to each other what
they thought of ruby I thought to myself "if everyone except me thinks
there is not enough documentation, maybe even though I think there is,
there isn't." When i started to put ruby to use for small personal
projects the pickaxe book was there and i found it adequate to my
requirements for learning ruby :).

I didn't want to push the issue at work if everyone came to the same
conclusion except for me (I didn't want to sound unprofessional or like a
zealot). I did bring up the pickaxe book and they *basically* said the
book is good as a starting point/base but felt there wasnt much out there
after that (i should mention we are big cookbook style documentation
fans). Basically everyone just agreed on this and that was that. It wasnt
like we were trying to figure out and take notes of the weak points in the
ruby documentation so we could present it to the community, it was just a
general conclusion everyone agreed on after 2 weeks of everyone looking
into ruby. I personally decided to do a dump of the decision to the
newsgroup, thinking back, it was probably a bad idea since i never wanted
to get into specifics for the fact that getting into specifics usually
draws out into long discussions and i have enough work as it is. I was
just trying to relay a company's decision and let the chips fall where
they may, i really thought i was clear about my intentions in my original
post but then again I'm not a writer.

I really don't want to bring this up at work and ask specifically for
their reasons or ask them to go back and dig some more to make me happy
:), this could possibly make me look like i am taking the issue personally
and not letting it drop. My point again with my original post was just to
point out that a team of people at a company looked into using ruby and
came to the conclusion that they really thought the language was great but
the final decision was "no" with the reason of not enough english
documentation. The reason I was mentioning about the python.org's
docs/module index is because people where i work think they are fantastic.
So for the sake of sounding redundant, all i really wanted to do is dump
this experience to the net for others to know, maybe i shouldnt have made
the suggestions of contributing to pleac and to port cpan modules. Anyway,
i do have work plus my own side project going on, the people who are
suggesting i am mouthing off but taking no action, well, you're right,
i'll leave the action in the ruby community to someone else if they feel
there is some needed to be taken. so now i shut up :).

I'm guessing (hoping) Hal will read this post, because this pretty much an
answer to both of you. I do appreciate the time Hal took to make his post,
but i just figured i would answer both here. Actually, this is pretty much
to everyone who has posted to this topic, sorry for my original post :).
This really has already taken to much of my time (i'm not trying to sound
important, pretty much i'm not :), but i am very busy), thinking back, i
should have just kept lurking.

sorry for the commotion,
stibbs