On Tue, 3 Jul 2001, Alex Chaffee wrote:
> 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.
>
This is not at *all* clear to me. For developer-oriented docs, the
overlap would seem to be zero -- the architectures of all three
environments are radically different. For user docs, there are
*similarities* between the versions, but they are by no means identical --
for example, IMHO it would be very confusing to have a single document
about JDBCRealm (just to pick an example) with three different ways to
configure it, based on which Tomcat version you are using. To say nothing
about the fact that the various versions of JDBCRealm are *not* identical
in their functionality or implementation.
And, many of the concepts you want to talk about in configuration docs are
*radically* different between versions.
+1 for separate doc trees per version (with a possible exception
identified in the next paragraph).
> 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.)
>
The "Application Developer's Guide" is pretty much the only existing doc
that is 99.9% portable across 3.2/3.3/4.0. That's courtesy of the fact
that it talks about web apps as defined in the servlet spec, and touches
only very lightly on anything that is Tomcat-version-specific.
There is probably 50% overlap if you talk about something like mod_jk
(i.e. the stuff about configuring httpd.conf). At that point, IMHO, it's
still better to have separate docs from a readability point of view.
But the killer issue is that the various versions are created by different
groups of developers, with different release schedules. Nobody is going
to be willing to wait for the omnibus documentation to be updated, or care
about shipping docs covering the "other" versions -- so you can count on
anything about the 3.3 version to be out-of-date in the 4.0 release
(for example), and vice versa.
Note that none of the above is influenced much by whether docs are stored
in a separate jakarta-tomcat-doc CVS repository or not (my preference is
"not" but that's a minor detail). But, even if it's all in the same
repository, in practice it's going to end up being separate
subdirectories, maintained and released indepently, anyway.
> 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.
>
The more work you make it for developers to write docs along with code,
the less docs are going to get written (by those developers). If the docs
are written by others it's not that big a deal -- but I personally like
the docs I write in the same CVS repository as the code that the docs
describe.
> 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... :-)
>
I'd be happy to see Alex take this task on.
> 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
>
Craig
