From: Gregory Brown Date: 2007-07-16T22:49:29+09:00 Subject: Re: graphing/charting application On 7/16/07, Chad Perrin wrote: > On Mon, Jul 16, 2007 at 09:34:15AM +0900, Gregory Brown wrote: > > On 7/15/07, Chad Perrin wrote: > > > > >I don't think project maintainers owe me something. I think failing > > >utterly to produce useful documentation is kind of a strange trend to see > > >in languages that come with excellent documentation tools, and I think > > >that my time is better spent using Scruffy (which has better > > >documentation) unless I want to actually become the Gruff project > > >maintainer myself. You're the one that assigned value judgments, whining > > >tone, and an attitude of entitlement to what I said -- not me. > > > > > >I think people who put words in my mouth really suck. > > > > You're right. What I said came off as harsh and rude, and I apologize > > for that. I actually was more springboarding into the general field > > of complaints I hear about Ruby libs not being properly documented, > > and I shouldn't have made it seem like I was directing that > > frustration at you. > > > > That having been said, undocumented software can be useful to those > > who are willing to read the source. Usually, unit tests are very > > illuminating so long as they exist, and if some examples are > > distributed with the source, that's enough to get going. I really > > wish that users would contribute more documentation to projects, > > because often maintainers simply don't have the time. > > > > So I suppose what I'm saying is that users should meet maintainers > > half way. When that doesn't happen, documentation doesn't get > > written. For example... you could probably help out gruff enormously > > by asking relevant questions about things you cannot figure out easily > > from the API docs. But if you have no time for that, well, that's > > understandable. But I feel like all of us are only entitled to get > > back what we put in. > > > > Again, sorry for flipping out before, it was unwarranted. > > Fair 'nuff. > > Frankly, I'm up to my eyeballs in projects -- both my own and those to > which I've already committed to helping out in peripheral ways, such as > contributing documentation (including the fact that I'm still trying to > find time to go through the TenDRA compiler's documentation and start > writing more). I don't have time to write the documention for every Ruby > library I want to use (slight exaggeration), though it'd be nice if I > did. I spent the last week dealing with a webhost that kind of blew up > in my face, and am trying to get everything moved to a different webhost > now with broken database exports, et cetera. What I've found in Ruport, which was the definition of poorly documented until very recently, that it's really helpful to have users just drop by the mailing list and say "I was able to get this and that done but now I've hit brick wall because *foo* is undocumented. This at least lets maintainers focus little bits of time on the most in demand sections of the system, instead of documenting things that may not be helpful to folks. It's amazing how little things like that can make a huge difference, even if it amounts to a user sending that one email and never responding again. (Of course, it's good to stick around too.) This mailing list is not the best place for those comments, because many package maintainers can't keep up with the posts here. :) > Maybe in a week I'll look back at this and have the perspective to see > that I took what you said more harshly than intended, or more personally > than you intended. When I wrote that reply, however, I just didn't > really take it very kindly. It's understandable. Tensions are high on the list lately, hopefully things will calm down soon.