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:[EMAIL PROTECTED]
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/
