tomcat-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Andy Armstrong <a...@tagish.com>
Subject Re: Tomcat Documentation Project
Date Tue, 03 Jul 2001 23:33:45 GMT
+1

guru@stinky.com 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.
> 
> 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: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/

-- 
Andy Armstrong, Tagish

Mime
View raw message