Re: JSwat cannot find the JPDA

Nathan Fiedler wrote:

> Sure I could reformat the README, but I fear that someone even more
> impatient than yourself would skip over the important bits and blame it
> on me. I'm sorry, but this is not my fault. If you had taken the 30
> seconds required to read the first couple of paragraphs, you would have
> saved yourself a lot of time.

I don't think I would characterize my behavior as impatient.  Someone who is
impatient wouldn't have pursued a solution as far as I did.  I actually believed
I was helping your cause.  And I still do.

There were actually /two/ developers looking at the README at the time we
attempted to install it.  Neither of us noticed the crucial instructions,
probably because we both expected salient information to be highlighted or set
apart in some way:  either by being indented or bulleted or otherwise formatted
in some way -- and we were in a hurry.  We didn't have all day to read every jot
and tittle of the document.  We had a bug we needed to find and we had about
thirty seconds to attempt to install and use your product.  If we couldn't easily
get the product working, then we would move on to something else which we knew we
could install and use.

Although the other developer and I did not have an extended discussion on the
philosophy of education, neither of us noticed the crucial information because of
the way it was formatted:  I think we both expected that the surrounding prose
would support, explain and expand on the salient information, but not contain it
to the exclusion of other forms of presentation.  You effectively use an HTML
table and indentation to emphasize important bits of information, and I think we
both expected that the most crucial piece of information of all would also be
somehow set apart or highlighted.  If it is not excruciatingly obvious how to get
an application running in thirty seconds, then something is wrong.  (BTW, I'm a
big fan of Java Web Start because it represents an almost fool-proof method of
distributing, installing and running an application.  You should consider it.)

We gave up after spending several minutes trying to get the application to work
and downloaded and installed another application (IDEA) instead -- and it worked
the first time.  I went back later for a second attempt at getting your
application running.  And once again I missed the salient information.  And I
don't think it is completely my own fault.

Let me make a suggestion with respect to instructional documentation:
repetition, redundancy or otherwise re-presenting material in more than one way
are excellent means to bring home a point.  The fact that neither in your FAQ nor
in your mailing list (e.g., in your response to my message) did you actually
RE-STATE the salient instructions means that you are failing at one of the basic
tenants of good instructional communication:  repetition of the important
points.  I had to dig /very deep/ into your mailing list before I found a
re-statement of the facts that I was looking for.  In this sense, your inability
to repeat and set apart a crucial piece of information outside of a single,
unemphasized, sentence embedded within the prose of your README file is a serious
failure of your documentation.

However, your non-interest in improving your documentation doesn't completely
surprise me, since most developers, especially open source, are more interested
in technical excellence rather than the excellence of the end-user experience.

But your refusal to acknowledge the soundness of my suggestion to use
-Djava.ext.dirs instead of modifying the JDK's distribution environment indicates
that technical excellence may not be your ultimate goal.  There are two things
going for this approach:  (1) it doesn't modify the distribution environment of
the JDK, and (2) it makes it more obvious that there is something special
required to run this application.

Alas, maybe some day you will see the light.  I have made my points as best as I
can.  As for now, my good will is coming to an end and I don't think it serves
any purpose to use up any more of your bandwidth.

cc