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 Wed, 02 Oct 2002 05:18:48 GMT
I feel your pain John, frustration with poor documentation is always a big 
sore spot.  But let's not line them all up and shoot them just yet, ok. 
They still need to get Tomcat 5 out the door.  ,"-)

We can only hope that Tomcat-dev (who is reading this list, I hope) will 
set up some sort of method where people can at least submit changes or 
updates or something better than what we have now. 

I've received at least 10 emails off-line and around 5 or so from the 
list, of people who have things to contribute.  We want to help, the 
question is, can something be done to move to a coordinated effort and who 
will do it.  I submit that it must be controlled and reviewed by the 
developers themselves.  They have access to the resources, we don't, and, 
they are the authorities on tomcat, they have to be the reviewing 
authority.

I know it will take no small effort to set this up but allot could be 
cloned from the good example of the Apache Documentation Project.

So, are there any developer types lurking out there.  We got some 
documentation help for you, do ya want it? 

rls





"Turner, John" <JTurner@AAS.com>
10/01/2002 05:11 AM
Please respond to "Tomcat Users List"

 
        To:     'Tomcat Users List' <tomcat-user@jakarta.apache.org>
        cc: 
        Subject:        RE: Documentation


> -----Original Message-----
> From: Glenn Nielsen [mailto:glenn@mail.more.net]
> Sent: Monday, September 30, 2002 6:18 PM
> 
> 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.

In my mind, these developers should be shot.  Or at least confined to a 
tiny
little box for an extended period of time.  Or maybe just put in charge of 
a
large data center running their software, and their email and cell phones
the only contact info on the 24/7/365 call list.  Not to rant, but any
developer, open source or not, that writes code but fails to provide good 
or
better documentation at the same time is a poor developer, regardless of
their technical skill, and regardless of their commitment or uncompensated
participation.  I'm no developer, but even I know that documentation is
key...I probably spend 60% of my sys-admin time writing recipes and docs 
for
other people to descibe what and how I did the things I did in the other
40%. 

I think that the argument that the developers "don't have time" is a
cop-out, especially under the Apache style of development and release
schedules.  There's no pressure to meet release dates in that mode of
development, so time is technically unlimited.  I would say it's more 
"don't
have the inclination because documentation isn't as cool as code and my 
ego
gets more of a boost from writing the latest whiz-bang feature or finding 
a
bug in some other guy's code than it does writing a doc that explains how 
to
perform an installation".  Which is a shame.

Besides, isn't Java self-documenting? ;)

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

I've been all through them, they're pretty much just a rehash of 4.0 docs
with a new design template.  The new design is pretty, granted, but that's 
a
far cry from where the docs should be.  The connector docs are a little
better, but in my opinion they don't cover nearly the amount of 
information
they should cover.  If they did, this list wouldn't get 100-150 messages
every night.

That said, I would gladly participate in any documentation project that is
started.  I could contribute several hours ( 3 < time < 10 ) each week.

> 
> Glenn
> 

John


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