tomcat-users mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From peter lin <peter....@labs.gte.com>
Subject Re: Documentation
Date Tue, 01 Oct 2002 13:02:05 GMT

I'm still cleaning up my old document on configuring
servletcontextlistener, and servlets, but I'd like to help also.  I also
think documentation is critical and would like to assist in that effort.

peter lin


"Turner, John" wrote:
> 
> > -----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