>> I'm sure that Geoffry would appreciate documentation patches.
>
>Sure . . . just as soon as I figure out how to use the library. With the
>information that's provided, I could probably sort out how to create
>simplest-case line graphs, but beyond that I'd have to put real time into
>it -- time I might prefer to spend on Scruffy, which it appears has
>better documentation.
This might sound rude, but I don't intend it to be offensive.
What makes you think maintainers of weakly documented projects care
whether or not *you* use their software?
This might sound rude, too, and I honestly don't intend it to be
offensive either:
If you think my statement implied that they should care whether or not
*I* use their software, you need to learn some reading comprehension
skills. I just answered the suggestion that I should contribute
documentation patches with some very concrete, real-world, reasonable
explanation for why that's unlikely -- even though I wish I *could*
submit documentation patches that easily.
What people forget to consider or refuse to consider is that adding
features to software or fixing bugs benefits the developers directly.
Writing documentation *might* benefit them, but often the folks who
write these things are very busy and are already working on other
important things, so documentation doesn't get written.
What I find most annoying about the whole situation is that tools like
RDoc were written specifically to ease the process of creating
documentation, to provide a solid beginning to that documentation so that
half the work is already done for someone that intimately knows the
software, but the end result is that many people seem to think that *is*
the documentation and never bother finishing the job. Documentation is
an important part of any development effort -- almost as important as the
software itself. Documentation is important for the same reason readable
code is important, and yet people who will argue for days on end about
the best way to eke that last bit of readability out of code will turn
around and go on producing software without even the most rudimentary
attempt to make documentation clear and useful.
Why bother creating a website with screenshots, marketing-speak
glorifications of the software, a Sourceforge project to entice other
users, and a gem package for distribution, without even doing the minimal
documentation necessary to make it generally useful? Time would be
better spent writing some useful documentation than creating image
galleries and using CSS to produce color gradients on the webpage.
I understand my goals are not the same as everyone else's, but I find it
quite difficult to figure out what goals are served by this sort of
example of priorities.
It's fine to say "I don't have the time to learn this undocumented
lib" and move on to another one, but criticizing projects for not
being documented is a baseless argument. You're asking why volunteers
don't volunteer more of their time to make *your* life easier, instead
of helping things along or at least *shutting up* when you're not
happy.
This got blown far out of proportion from the intent of my previous
statements, thanks to comments about "whining" and passive-aggressive
insinuations that I should produce documentation or just enjoy the
software without any documentation.
I apologize for a mini-rant here, but users who think project
maintainers owe them something really suck.
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.
···
On Mon, Jul 16, 2007 at 01:53:25AM +0900, Gregory Brown wrote:
On 7/15/07, Chad Perrin <perrin@apotheon.com> wrote:
--
CCD CopyWrite Chad Perrin [ http://ccd.apotheon.org ]
They always say that when life gives you lemons you should make lemonade.
I always wonder -- isn't the lemonade going to suck if life doesn't give
you any sugar?