+1 to everything, esp "docs in same project"
- r
> -----Original Message-----
> From: Craig R. McClanahan [mailto:[EMAIL PROTECTED]]
> Sent: Saturday, July 07, 2001 1:42 AM
> To: [EMAIL PROTECTED]
> 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
>
>
>
