Graphing/charting application

ruby-talk
21

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

···

On Mon, Jul 16, 2007 at 09:34:15AM +0900, Gregory Brown wrote:

On 7/15/07, Chad Perrin <perrin@apotheon.com> 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.

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

22

Makes sense.

If I had more free time (new job + still a lot of pending freelance work,
so not any time soon), I might start going through some of the major Ruby
packages and updating the docs. They're often pretty vague.

-s

···

In message <20070715224215.GE19237@demeter.hydra>, Chad Perrin writes:

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.

23

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 <perrin@apotheon.com> wrote:

On Mon, Jul 16, 2007 at 06:34:22AM +0900, Peter Seebach wrote:

In message <20070715212911.GC18755@demeter.hydra>, 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."

24

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

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 7/16/07, Chad Perrin <perrin@apotheon.com> wrote:

On Mon, Jul 16, 2007 at 09:34:15AM +0900, Gregory Brown wrote:
> On 7/15/07, Chad Perrin <perrin@apotheon.com> wrote:

25

damn that google. heres a sanely snipped response below.

···

On 7/16/07, Gregory Brown <gregory.t.brown@gmail.com> wrote:

On 7/16/07, Chad Perrin <perrin@apotheon.com> 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. :slight_smile:

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