[EMAIL PROTECTED] wrote:
>
> Leaving aside the issue of file format for just one second...
>
> Are we agreed on the following?
>
> 1. Tomcat documentation sucks :-)
>
Thats a strong word, some parts are very good, some could use work.
> 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.
>
> Looking at it in reverse, the fact that someone is using an old version
> of Tomcat shouldn't mean they're forced to use an old version of the
> documentation. Instead, a chapter on, say, web application deployment
> may need to have a sidebar describing changes between 3.x and 4.x, but
> assuming 4.x isn't *radically* different, they can both use the same
> core text. (In cases where 4.x *is* radically different, it would just
> have a separate document/chapter, with the 4.x specificity clearly
> labelled in the title.)
>
> I know the 4.x crew have begun the process of creating a separate
> documentation set, including xdocs, and this is great. If it's too much
> work to integrate 3.x and 4.x then maybe they should remain separate CVS
> projects too, but it may still be desirable to have a separate CVS
> project anyway.
>
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. 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.
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.
In summary:
jakarta-tomcat-doc only provides generic documentation, like JSP 1.1 web app, etc.
jakarta-connectors does separate documentation for each connector/protocol.
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.
> 3. There needs to be a better index/TOC for the documentation we do
> have, and a reorganization of the redundant / outdated / wrong parts of
> the existing docs (the Apache config stuff comes to mind).
>
It is always a good thing to keep docs up to date.
> 4. Someone or some small group of people should take responsibility for
> making this happen (before we "run out of steam"), regularly submitting
> proposals and keeping the rest of the group apprised of developments and
> decisions, but retaining some authority. Let's call this person/people
> the Documentation Czar. I'm not proposing he/they have any real
> authority over the content, but just over organizing it, deciding where
> to place it, and forming "to do" lists for documents/chapters that need
> to be written or proofed or tech edited or revised.
>
It would be great if someone were willing to volunteer.
> If we agree on the above, then there's a good chance I'd volunteer to be
> the Doc Czar, even though I think it's a lot of work. I've been managing
> the jGuru Tomcat FAQ for a year, and the Servlets FAQ for longer, so I
> at least have some idea of the scope of this kind of organizational
> task. (Note that I'm not suggesting I actually *write* all this new
> documentation... :-)
>
> Maybe a better term would be "Doc Editor" or "Editorial Board". And
> maybe I'm being too anal in proposing it; maybe the open source process
> will ensure the job gets done by interested developers even without the
> title.
>
> - Alex
>
> --
> 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/
--
----------------------------------------------------------------------
Glenn Nielsen [EMAIL PROTECTED] | /* Spelin donut madder |
MOREnet System Programming | * if iz ina coment. |
Missouri Research and Education Network | */ |
----------------------------------------------------------------------
