Mailing-List: contact tomcat-dev-help@jakarta.apache.org; run by ezmlm
Precedence: bulk
Reply-To: tomcat-dev@jakarta.apache.org
Date: Tue, 10 Jul 2001 12:44:50 -0700
From: guru@stinky.com
To: tomcat-dev@jakarta.apache.org
Subject: Re: Suggestions (was Re: hello everyone (regarding documentation))
Message-ID: <20010710124450.A4567@stinky.com>
Reply-To: alex@jguru.com
References: <LAW2-F100KRNZSPGNkY0000800b@hotmail.com>
 <3B4ABF30.366458E9@tid.es>
Mime-Version: 1.0
Content-Type: text/plain; charset=iso-8859-1
Content-Disposition: inline
Content-Transfer-Encoding: 8bit
User-Agent: Mutt/1.2.5i
In-Reply-To: <3B4ABF30.366458E9@tid.es>;
 from afm229@tid.es on Tue, Jul 10, 2001 at 10:39:12AM +0200

On Tue, Jul 10, 2001 at 10:39:12AM +0200, Alex Fern�ndez wrote:
> Hi Hiten!
> 
> hiten pandya wrote:
> > i am planning to start my own documentation project for Tomcat 3.3 and 4.0.
> > The different thing about this project is that, i am going to port all of
> > the tomcat documentation to XML Docbook format.
> 
> Not speaking officially, I'm not a committer: if you want to document
> Tomcat, then go ahead and good luck!
> 
> Your focused work can do lots for the docs: you will probably end before
> the "committee" decides the right format for Tomcat docs :)

OK, I appreciate the :-) but... that's not *quite* fair.  We're
closing in on a decision, and if you want to write new stuff now you
should just go ahead and do it.  Use text or HTML or even Word.  I
think using DocBook is premature.

I don't think a wholesale conversion of existing docs to DocBook will
be a good use of anyone's time right now.  Maybe in a week or two
we'll be converting them to Anakia or DocBook but not just yet.

> Just a suggestion:
> > Though i am not very good at docbook but i think i can cope. Once the
> > documentation is complete, I will submit it to the main tomcat development
> > team.
> 
> Don't wait till everything is ready; send your updates regularly to the
> dev list, so folks can criticize your work and point possible mistakes.
> That way, you can change course in a timely manner; otherwise you might
> find at the end that a chapter is unnecessary and another one is missing
> :)

Before you write a chapter (or article or HOWTO or whatever you want
to call it), please take a look at (a) the existing docs, and more
importantly (b) the Table of Contents and see if it fits in anywhere.
Then let the list know what you're working on.  We're trying to
organize the docs so there's no redundant information.

(For instance, there's lots of information on configuring Apache
scattered among half a dozen howtos and FAQs right now.  Most of it is
now out of date, and it'll be impossible to bring it all current.  I'd
like there to be one chapter on "integrating with Apache," with
subsections for "mod_jk," "mod_webapp", "mod_jserv," and so on -- and
since the subsections can rely on the introduction of the Apache
chapter, they won't have to duplicate information that's already been
covered above, and won't confuse anybody.  On the Tomcat Forum I
regularly get questions where people have read a mod_jserv howto
instead of a mod_jk howto and they don't even realize there's a
difference, since they're both called "Configuring Apache" without
mentioning the name of the connector.)


-- 
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/