tomcat-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject Re: Suggestions (was Re: hello everyone (regarding documentation))
Date Tue, 10 Jul 2001 19:44:50 GMT
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             
jGuru - Java News and FAQs
Creator of Gamelan       
Founder of Purple Technology
Curator of Stinky Art Collective

View raw message