tomcat-users mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Turner, John" <JTur...@AAS.com>
Subject RE: Documentation
Date Tue, 01 Oct 2002 12:11:31 GMT

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


Mime
View raw message