tomcat-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject Re: Tomcat Documentation Project
Date Wed, 04 Jul 2001 02:43:05 GMT
On Tue, Jul 03, 2001 at 09:34:39PM -0500, Glenn Nielsen wrote:
> > 1. Tomcat documentation sucks :-)
> > 
> Thats a strong word, some parts are very good, some could use work.

Agreed; I was just using the term from a prior thread.

> > 2. There needs to be a new CVS project called jakarta-tomcat-doc.
> > 
> > My reasoning is that we want to avoid the fragmentation of documentation
> > into different trees for 3.2, 3.3, and 4.0.  Why?  Because a lot of
> > documentation would apply equally to all versions.

> My big concern about your proposal is that the documentation would get
> disjointed.  With too many if this version or that version qualifiers
> in the docs. 

This would be an editorial decision, whether a particular topic is
better as one document with N sidebars, or as N separate documents.
Sometimes one would work, sometimes the other.

> I really think the docs should be built for each specific
> container, providing documentation only for that container.  This would
> be better for the user since they are only using one of the three
> versions of Tomcat.

By "container" do you mean 3.2 vs. 3.3 vs. 4.0 or Apache vs. IIS
vs. standalone?
> I could see a need for jakarta-tomcat-doc for anything that is generic
> and not Tomcat version or connector specific.  Then let the document
> builds for the individual Tomcat versions pull in anything they can use from
> the generic docs or the individual connector docs in jakarta-connectors.

I think that encouraging Tomcat subprojects to pull in documentation
risks fragmenting versions.  If every one of 3 or more groups has a
slightly different version of a document, then how do we correct an
error?  Three separate commits?  Yuk.

Doing a unified doc is a tough problem, and we'd have to spend some
time looking at a full outline of all docs, present and future (which
right now doesn't exist, except that I've made a draft which I'm not
ready to share yet), before we could decide for sure that it would
work out.  But the advantages are enough to make me risk trying.

> In summary:
> jakarta-tomcat-doc only provides generic documentation, like JSP 1.1 web app, etc.

Nah, then it's useless, it just becomes Servlets documentation, and
there's already plenty of that.

>  jakarta-connectors does separate documentation for each
> connector/protocol.

These would be a subdirectory of the doc project.  All connector
authors would be able to submit/commit connector docs.

> jakarta-tomcat/jakarta-tomcat-4.0 does their own version specific docs and
> merges in any useful docs from jakarta-tomcat-doc and/or jakarta-connectors.

See above for my trouble with merging.  I really think that once you
start splitting off, you risk the scenario where someone says "Just
check the docs" and someone else says "I did, what are you talking

> It would be great if someone were willing to volunteer.

I'm not *quite* ready for the commitment ;-)

Alex Chaffee             
jGuru - Java News and FAQs
Creator of Gamelan       
Founder of Purple Technology
Curator of Stinky Art Collective

View raw message