tomcat-users mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Anthony Milbourne <anthony.milbou...@becta.org.uk>
Subject RE: Documentation
Date Tue, 01 Oct 2002 13:28:12 GMT
Hi

-1 for shooting developers :-)

I can see your point John, but in the real world people are slack and miss
bits.  Also, as has been pointed out, writing technical notes for technical
people is a very different skill to writing a user manual for lay-people.  I
would rather have the best developers doing the development and the best
authors writing the docs.  Also a lot of minor patches and fixes are
submitted by people other than the core developers - often without updates
to the docs (if they are needed).

I think the doc project is a good idea.  I don't feel I know enough about
Tomcat to contribute source (I doubt they would take it :-), but I do feel I
have used Tomcat enough to comment on, and maybe even contribute, docs.

I am certainly willing to contribute to a project - although I suspect there
are people more qualified who have already volunteered.

		Anthony.

> -----Original Message-----
> From:	Turner, John [SMTP:JTurner@AAS.com]
> Sent:	01 October 2002 13:12
> To:	'Tomcat Users List'
> 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.
> 
> 


**********************************************************************
This email and any files transmitted with it are confidential and
intended solely for the use of the individual or entity to whom they
are addressed. If you have received this email in error please notify
the system manager.
This footnote also confirms that this email message has been swept by
MIMEsweeper for the presence of computer viruses.
www.mimesweeper.com
**********************************************************************


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