Yes, I've seen the new docs, and it looks like they're making an good
effort there. The trouble comes with trying to maintain them. By that I
mean, when new features are added to Tomcat the docs should reflect them.
I don't expect developers to be expert at technical writing, that is
another career field all in itself. When documentation becomes stale or
is not clear to most you have a problem that requires time to correct.
Complicated opensource products require that developers spend more and
more time with just developing. Tomcat has reached the plateau where it
is just not cost effective for the developers to maintain the
documentation any longer. Their time is better spent developing the code,
and informing a documentation effort of the new procedures, configuration,
or capability. The documentation project then takes care of all the nit
picking details required of a good documentation project. The issues of
DTD's, CSS, style, third person vs 1st, formal vs informal, and language
translation, to name of few, are coordinated by the project to come up
with a coherent body of knowledge that mirrors the project itself.
Right now if you want to learn the inner workings of Tomcat you have to
read the source, pick up clues from various good hearted souls around the
net, experiment through trial and error, make buddies with someone who's
done it for years, or pay for instructions.
For a documentation project to get off the ground the developers have to
push for it. They have to be in control of it. Resources for it have to
be allocated. (CVS) A single point of authority has to be instituted, an
authoritive reference (website) has to initiated, a peer review has to be
established. After all this is done then How To's, FAQ's, basic
explanations of terms, procedures, and advise, all from one authoritive
source will go a long way toward clearing the air and removing the voodoo
from Tomcat.
One of the big reasons for why commercial outfits tend to go with a
commercial container is because of the technical climate surrounding the
installation, configuration, and maintenance of Tomcat. If this was
simplified or if there was one dependable point of reference that answers
could easily be drawn from, it would remove one of the biggest bullets
from the gun that decision makers use to shoot down the use of Tomcat.
When was the last time that you heard of Apache being disregarded as a
viable alternative because it was too hard to install, configure or
maintain? I submit that one of the biggest reasons that Apache enjoys the
percentage of internet installs that it does is because of it's ease of
access to clearly understood documentation.
Ok, ok, I know, I'm long winded, so I'll shut up now.
I'm really just saying that it's time for it to happen with Tomcat. I'm
willing to contribute toward it, I'm sure others will too.
rls
Glenn Nielsen <[EMAIL PROTECTED]>
09/30/2002 03:18 PM
Please respond to "Tomcat Users List"
To: Tomcat Users List <[EMAIL PROTECTED]>
cc:
Subject: Re: Documentation
Robert L Sowders wrote:
> Since most of the questions to tomcat-users list concern installation
and
> configuration issues it demonstrates that there is a real need for
Tomcat
> to have a "documentation project" that it's users can contribute to.
Right
> now most of the documentation consists of the xdocs which are pretty
good,
> but can be so much more. The developers obviously have little time to
> maintain the present documentation and there is such an apparent need
that
> I wonder why a project for the documentation has not been started.
>
I would tend to agree with the above, those writing the code either don't
have the inclination or time to write up good documentation.
Have you looked at the latest docs for Tomcat 4.1? Much better jk
documentation,
existing docs updated, and even some new documents at:
http://jakarta.apache.org/tomcat/tomcat-4.1-doc/index.html
Regards,
Glenn
--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
