Tomcat Documentation Project

[Alex Chaffee <al...@jguru.com>]

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

RE: Tomcat Documentation Project

["Rob S." <rs...@home.com>]

+1 to everything, esp "docs in same project"

- r

> -----Original Message-----
> From: Craig R. McClanahan [mailto:craigmcc@apache.org]
> Sent: Saturday, July 07, 2001 1:42 AM
> To: tomcat-dev@jakarta.apache.org
> Subject: Re: Tomcat Documentation Project
>
>
>
>
> 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
>
>
>

Re: Tomcat Documentation Project

["Craig R. McClanahan" <cr...@apache.org>]

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