tomcat-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Alex Chaffee <g...@stinky.com>
Subject Re: [DOC] Vote on oustanding doc issues?
Date Wed, 11 Jul 2001 15:26:36 GMT
Craig R. McClanahan wrote:

> 
> On Mon, 9 Jul 2001, Alex Chaffee wrote:
> 
> 
>>>Bundle the 3.2.x docs with 3.2.x and only have the 3.3 docs online ("latest
>>>Tomcat release").  If you want the 3.2.x docs, get them with the binary or
>>>whatever.  I certainly don't think we should keep old versions of
>>>documentation updated.  I mean, why would updated 3.0 or 3.1 docs be useful?
>>>
>>>
> 
> Unless and until there's a 3.3 or 4.0 final release, *3.2* is the "latest
> Tomcat release", and deserves to be documented on the web site.


OK, but my point is that as we improve the 3.x docs -- regardless of the 
value of x -- the 3.2 docs will become less relevant.

Right now there are many differences between the 3.2 and 3.3 docs, but 
they're mostly in the connector docs, which AFAIK haven't changed much if at 
all in operation. This leads me to conclude that the docs in the 3.3 tree 
are just as valid when applied to 3.2, except that they're better docs, 
since more people have had a chance to revise them.  That's why I'd like to 
remove the "Tomcat 3 docs that happened to be in the depot at the time 3.2 
shipped" in favor of "the latest version of the Tomcat 3 docs (which happen 
to be in the 3.3 dev tree)".

Perhaps the easiest way to do this would be with a separate depot. I'm 
shying away from that for the reasons you (Craig) brought up.  It's nice for 
docs to be in the same depot as the code...

> There's no reason to banish the current Tomcat released version, or any
> other version that is being actively developed.  And it's quite easy to
> arrange the user interface so that it's obvious which version you are
> looking at (for example, including "Tomcat X.Y" in the header or footer of
> the pages about that version).


Again, apart from 3 vs 4, the difference between versions 3.2 and 3.3 is 
small, as far as docs are concerned, so announcing "Tomcat 3.2" in the 
header wouldn't be very salient, and would just promote forking of docs. We 
seem to be in this quandary because the docs have not really been part of 
the release process -- they get released slapdash relative to the code 
milestones.


By the way, it seems like the majority of the existing documentation is 
about installation. If there were a clean, robust install script, it would 
remove 90% of the text on the site. Maybe before we write (rewrite) install 
docs we should write an install script.  I know that was on your todo list 
for 4 -- how's that coming?


-- 
Alex Chaffee                       mailto:alex@jguru.com
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/


Mime
View raw message