«

On Mon, Jul 16, 2007 at 01:53:25AM +0900, Gregory Brown wrote:
> On 7/15/07, Chad Perrin <> wrote:
>
> >> 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.

--
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?

On Mon, Jul 16, 2007 at 06:34:22AM +0900, Peter Seebach wrote:
> In message <>, Chad Perrin writes:
> >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.
>
> I think many developers underestimate the significance of documentation
> to projects. Of course, most of us have at least some practice figuring
> things out without documentation, reading source, and so on...

True. It's a shame that there isn't better documentation for some
projects, however -- especially since that often means someone will go
use something else (with better documentation) instead. While I could
eventually puzzle out how to use Gruff effectively, for instance, I'd
rather have something with good documentation at my fingertips than have
to pore over source code just for a trivial use of the library.

Since I've been accused of something akin to solipsism before in this
discussion, I'll be clear: I'm not saying that I, personally, am an
important user to whom developers must cater. Read my personal
experience as a symptom of a deeper problem with the lack of quality
documentation, please.


>
> But putting in a few years as a writer leaves me more concerned with
> documentation than I used to be. I'll say that much.

Writing what amounts to tutorial documentation for money in the last few
years has certainly improved my understanding of the importance of
documentation -- but I think the biggest change to my perspective is in
the fact that I'm using libraries much more these days than I used to,
and thus finding poor library documentation far more problematic than I
used to.

--
CCD CopyWrite Chad Perrin [ http://ccd.apotheon.org ]
Marvin Minsky: "It's just incredible that a trillion-synapse computer could
actually spend Saturday afternoon watching a football game."

This may be OT at this point on the conversation but, I've used XML/
swf charts for quite a while now and really like it

Sent from my iPhone

On Jul 15, 2007, at 6:42 PM, Chad Perrin <> wrote:

> On Mon, Jul 16, 2007 at 06:34:22AM +0900, Peter Seebach wrote:
>> In message <>, Chad Perrin
>> writes:
>>> 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.
>>
>> I think many developers underestimate the significance of
>> documentation
>> to projects. Of course, most of us have at least some practice
>> figuring
>> things out without documentation, reading source, and so on...
>
> True. It's a shame that there isn't better documentation for some
> projects, however -- especially since that often means someone will go
> use something else (with better documentation) instead. While I could
> eventually puzzle out how to use Gruff effectively, for instance, I'd
> rather have something with good documentation at my fingertips than
> have
> to pore over source code just for a trivial use of the library.
>
> Since I've been accused of something akin to solipsism before in this
> discussion, I'll be clear: I'm not saying that I, personally, am an
> important user to whom developers must cater. Read my personal
> experience as a symptom of a deeper problem with the lack of quality
> documentation, please.
>
>
>>
>> But putting in a few years as a writer leaves me more concerned with
>> documentation than I used to be. I'll say that much.
>
> Writing what amounts to tutorial documentation for money in the last
> few
> years has certainly improved my understanding of the importance of
> documentation -- but I think the biggest change to my perspective is
> in
> the fact that I'm using libraries much more these days than I used to,
> and thus finding poor library documentation far more problematic
> than I
> used to.
>
> --
> CCD CopyWrite Chad Perrin [ http://ccd.apotheon.org ]
> Marvin Minsky: "It's just incredible that a trillion-synapse
> computer could
> actually spend Saturday afternoon watching a football game."
>

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.

-greg

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.

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.

Let's "kiss" and make up, or whatever the kids are doing these days.

By the way, that URL in my signature won't work until I get some more
stuff migrated to the new webhost. Dammit. I guess that serves as a
needed reminder. . . .

--
CCD CopyWrite Chad Perrin [ http://ccd.apotheon.org ]
print substr("Just another Perl hacker", 0, -2);

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.

damn that google. heres a sanely snipped response below.

On 7/16/07, Gregory Brown <> wrote:
> On 7/16/07, Chad Perrin <> wrote:

> > > 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.
>

On Jul 15, 2007, at 09:26 , Chad Perrin wrote:

> Is there some kind of rule that states that, when something like
> RDoc is
> available, library developers are disallowed from producing good
> documentation? I'm constantly frustrated by the fact that many
> libraries
> figure a skeleton map of available methods constitutes
> "documentation".

Is there some kind of rule that states that, when something is freely
made available to the public, the users are disallowed from being
polite? I'm constantly frustrated by the fact that many users figure
a scathing comment in IRC or a mail to ruby-talk constitutes
"constructive criticism".

Why do so many users never seem to bother to put in an ounce of
effort in looking at something for every pound of effort the author
puts into writing it in the first place?

It took me less than 60 seconds to download gruff, unpack it, and
notice that there is over 92K(!!) of tests. PLENTY of live testable
"documentation" right there. But instead of doing something like
that, your sense of entitlement made you think the above paragraph
was a good idea.

...Made slightly redundant by Gregory's replies, but I had to get it
off my chest...

On Tue, Jul 17, 2007 at 07:49:16AM +0900, Ryan Davis wrote:
>
> On Jul 15, 2007, at 09:26 , Chad Perrin wrote:
>
> >Is there some kind of rule that states that, when something like
> >RDoc is
> >available, library developers are disallowed from producing good
> >documentation? I'm constantly frustrated by the fact that many
> >libraries
> >figure a skeleton map of available methods constitutes
> >"documentation".
>
> Is there some kind of rule that states that, when something is freely
> made available to the public, the users are disallowed from being
> polite? I'm constantly frustrated by the fact that many users figure
> a scathing comment in IRC or a mail to ruby-talk constitutes
> "constructive criticism".

Is there some kind of rule that states that everyone who takes note of
what I said has to blow it out of proportion, assign intent to it that
wasn't present, and generally try to put words in my mouth?


>
> Why do so many users never seem to bother to put in an ounce of
> effort in looking at something for every pound of effort the author
> puts into writing it in the first place?
>
> It took me less than 60 seconds to download gruff, unpack it, and
> notice that there is over 92K(!!) of tests. PLENTY of live testable
> "documentation" right there. But instead of doing something like
> that, your sense of entitlement made you think the above paragraph
> was a good idea.

Lay off the caffeine. You're assuming an awful lot.


>
> ...Made slightly redundant by Gregory's replies, but I had to get it
> off my chest...

You should have sat on it.

--
CCD CopyWrite Chad Perrin [ http://ccd.apotheon.org ]
Thomas McCauley: "The measure of a man's real character is what he would do
if he knew he would never be found out."

On Jul 16, 2007, at 17:05 , Chad Perrin wrote:

> On Tue, Jul 17, 2007 at 07:49:16AM +0900, Ryan Davis wrote:
>>
>> On Jul 15, 2007, at 09:26 , Chad Perrin wrote:
>>
>>> Is there some kind of rule that states that, when something like
>>> RDoc is
>>> available, library developers are disallowed from producing good
>>> documentation? I'm constantly frustrated by the fact that many
>>> libraries
>>> figure a skeleton map of available methods constitutes
>>> "documentation".
>>
>> Is there some kind of rule that states that, when something is freely
>> made available to the public, the users are disallowed from being
>> polite? I'm constantly frustrated by the fact that many users figure
>> a scathing comment in IRC or a mail to ruby-talk constitutes
>> "constructive criticism".
>
> Is there some kind of rule that states that everyone who takes note of
> what I said has to blow it out of proportion, assign intent to it that
> wasn't present, and generally try to put words in my mouth?

The above is a direct quote of yours, so I didn't put words in your =20
mouth. I found it snide and rude because _it_is_snide_ so I didn't =20
blow it out of proportion. At worst, I could be guilty of assigning =20
intent, except, it really was your intent to be snide, wasn't it? =20
That seems plain as day to the rest of us.

snide |sn=C4=ABd| |sna=C9=AAd| |sn=CA=8C=C9=AAd|
adjective
1 derogatory or mocking in an indirect way : "snide remarks about my =20
mother."
=E2=80=A2 (of a person) devious and underhanded : "a snide divorce =
lawyer."

snide
adjective
"at his final snide comment, she slapped him across the face"
disparaging, derogatory, deprecating, denigratory, insulting, =20
contemptuous; mocking, taunting, sneering, scornful, derisive, =20
sarcastic, spiteful, nasty, mean.