Leaving aside the issue of file format for just one second...
Are we agreed on the following?
1. Tomcat documentation sucks :-)
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.
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).
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.
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/
