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 the
PickAxe 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 since everyone came to the same
conclusion except for me. I didn't want to sound unprofessional or like a
zealot and in the end i really do agree with them even though the docs are
ok for me using ruby at home. as far as the pickaxe book goes, they
*basically* said the book is good as a starting point/base but felt there
wasnt much solid documentation out there aside from that (maybe i should
mention we are big cookbook style documentation fans? anyway...).
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 them 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
leads into long discussions and i have enough stuff to do, plus
getting into specifics on a topic such as this could lead to me
slipping into a new side project that i don't have time for nor do i want.
When i say *overall* and *general* that is what i mean and for a well
thought-out reason. 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, then again, I'm not a writer.

I'm not going to bring this up at work and ask specifically for
their reasons in detail while i take notes with a pen and paper nor do i
want to ask them to go back and dig some more to make me happy. Doing so
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 python.org's docs
are fantastic (they also feel the same about perl's and PHP's). So for the
sake of sounding *very* redundant, all i really wanted to do is dump this
experience to the net for others to see, 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 taking in the ruby community to someone else if they
feel there is some action needed to be taken. So after this post 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