From: ptkwt@...1.aracnet.com (Phil Tomson) Date: 2002-09-01T03:37:26+09:00 Subject: Re: suggestions to the Ruby community In article , stibbs wrote: >On Fri, 30 Aug 2002 20:48:02 -0400, Phil Tomson wrote: > >> In article , stibbs >> wrote: >>> >> >> 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 >:). Me too :) > >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, No problem. Thanks for your input. I'm sure there is a lot of room for improvement of documentation - maybe we should take a look at how Python's docs are done. Phil