tomcat-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From g...@stinky.com
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
about?"

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

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

-- 
Alex Chaffee                       mailto:alex@jguru.com
jGuru - Java News and FAQs         http://www.jguru.com/alex/
Creator of Gamelan                 http://www.gamelan.com/
Founder of Purple Technology       http://www.purpletech.com/
Curator of Stinky Art Collective   http://www.stinky.com/

Mime
View raw message