tomcat-users mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Robert L Sowders" <rsowd...@usgs.gov>
Subject Re: Documentation
Date Tue, 01 Oct 2002 01:14:59 GMT
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 <glenn@mail.more.net>
09/30/2002 03:18 PM
Please respond to "Tomcat Users List"

 
        To:     Tomcat Users List <tomcat-user@jakarta.apache.org>
        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:tomcat-user-unsubscribe@jakarta.apache.org>
For additional commands, e-mail: <mailto:tomcat-user-help@jakarta.apache.org>





--
To unsubscribe, e-mail:   <mailto:tomcat-user-unsubscribe@jakarta.apache.org>
For additional commands, e-mail: <mailto:tomcat-user-help@jakarta.apache.org>


Mime
View raw message