Suggestions (was Re: hello everyone (regarding documentation))

[Alex Fernández <af...@tid.es>]

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 :)

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
:)

Un saludo,

Alex.

Re: Suggestions (was Re: hello everyone (regarding documentation))

[Christopher Cain <cc...@mhsoftware.com>]

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 :)

LLAMF! True that.

> 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.
[snip]

Am I the only one that initially read that as "send your updates
regularly so that folks can criticize you and your pointless mistakes"?
Alex deals some very sage advice here, but when I first hit "Reply" he
was about to get some even higher praise for the funniest pointed
sarcasm I had heard in quite some time.

...

Uhhh ... I guess you had to be there. In any event, Alex's advice is
quite sound, FWIW.

Re: Suggestions (was Re: hello everyone (regarding documentation))

[gu...@stinky.com]

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/