On Fri, 28 Oct 2005 09:48:26 +0200
Willem Grooters <[EMAIL PROTECTED]> wrote:
Another important issue that I read in Kurt's
complaints, is the incompatibility of different Java
versions.
I too have seen this.
However, I have to say that the incompatibility wasn't as
much with Java as it was with the tool. For example,
Tomcat 4 and Tomcat 5 are different animals. Both run on
Java 1.4 and 1.5. However, each has a different way of
configuring the server and the application that you
deploy. This IS the nature of the tool - and is NOT
unique to Open-Source.
I find myself, at times, using the generic term Java to
mean the tools as well as the language. However, my use
of Java to refer to the tools and applications I use and
make is INCORRECT. Tomcat is NOT Java. Nor is Axis Java
or SOAP. They are tools.
In reading Kurt's comments, I fear he is using the term
Java to refer to many things, not just the language or the
VM. And this is unfair. Java 1.5 WILL run every
application I write in Java 1.4 (sans bugs in the compiler
implementation or the JVM of course...) But Tomcat 5 will
NOT run a Tomcat 4 web application - nor should it.
The folks that write the many applications that we rely
upon go to great lengths to try to tell us what has
changed when they release a version of their software.
These patch notes and release readme's are an important
part of every piece of software - whether it's FOSS or
proprietary.
Documenation is another thing. If it exists (and alone
that is already a problem) it should be clear and
consistent. It often isn't: It's full of jargon,
too much omission of knowledge, therefore hard
to understand for newcomers, and asking the
community is not always a help: it takes too much
time to filter what's usable and what's not, and
to give things a try and find out why it doesn't
work; It's a good way of asking more specific things,
not the basic ones. But you NEED to if documenation
is simply missing.
Documentation is a problem in EVERY project, whether it's
FOSS or proprietary.
When was the last time you looked at the books on the
shelf at your local book store? How many Java books are
there? And much of that content describes the same
concepts and content over and over.
Creating documentation for a newbie to a project is the
most difficult thing to accomplish. Why? Just because
I'm a newbie to AXIS and SOAP doesn't mean I'm a newbie to
Java, Tomcat, Web Services, etc. So the question that
each author needs to ask is: where do I start? And the
answer to that question is usually the focus of the
book/documentation.
You may notice from this reply e-mail, that I can write
fairly well (although not perfectly...) I've attempted to
write documentation and to provide additional information
to existing material. And I can tell you from first hand
experience that writing docs is the most thankless of jobs
- especially when I'm doing it for free!
Why is it that there are so many books and publications in
existance today? People who write well want to get
compensated for their efforts - as they should. Look at
any hardware or software vendor. They have *teams* of
paid writers that produce their materials.
We in the FOSS community are so blessed it isn't funny. We
have access to the best documentation that can ever
exist for a project: the source. But, having said that,
I can say with 100% confidence that I can't follow 99% of
the source of the Axis project. It's not that I'm stupid,
or that the author of the code I'm looking at is so much
smarter than I am (although I'm sure that's true!)
My problem is putting into context the code I'm looking at
in relation to the problem/task I'm attempting to solve.
And no matter how well the code is documented, it's never
enough.
Another problem all products have with their documentation
is you must almost be an expert with the tool before you
can really write the documentation. Because who knows the
tool better than the expert that created it? And writing
documentation is not something most developers like to do.
Bob
