On Sun, 29 Jul 2001, Rob S. wrote:
> Was there ever any resolution to the docs discussion on -general? I wish I
> could contribute to a doc gen or format tool conversation, but I'm far from
> an expert in that field. Standing up and waving my arms about the whole
> topic probably isn't going to do much either, so I'll talk about something
> else for now =)
>
It's not formally resolved, but it's time for us to just "do
something" instead of just talk about it.
> Right now, the current structure of the docs (index.xml) looks like this:
>
> - Introduction
> - Getting Started
> - Administrators
> - App Developers
> - Tomcat Developers
>
> The "Introduction" and "Getting Started" sections are pretty much done -
> there are documents on building, installing, and running Tomcat in there
> now. Craig is working on porting the "App Developers" guide this weekend.
>
You can see the fruits of my labors in the "tomcat-docs" web app. This
can be generated (if you've got the source distribution) by typing "ant
tomcat-docs" at the top level. I'm also going to upload a snapshot of the
output to the Tomcat web site for easy perusal.
If you've got some text, I'd like to try integrating it into the
"tomcat-docs" experiment. The Anakia stylesheet that was written for
jakarta-site2 (and therefore the XSLT version that I checked in, because I
tried to be as similar as possible) has some real quirks when you try to
use it for different projects -- but the document content itself should be
able to be pretty independent of that.
You'll also note that I punted on the Getting Started and just linked in
the text files from the top-level directory of the distribution. I'm fine
with doing whatever's appropriate, but we do need *something* in text-only
format there, and we should minimize duplication that will require things
to be updated more than once later.
> What's the top priority for the "Administrators" section?
IMHO, documenting the various settings in server.xml is critical. It
really needs to be done in at least two flavors -- reference material on
all the possible options (pretty much done in HTML, needs to be
converted), and a more "user's guide" approach to "if you want to do
this, here's how you do it."
The current docs try to mix these styles a little, and I'm not so sure it
is very effective.
> Did anyone take a
> look at the "Running Multiple Instances" thing? Was that like, too
> worthless to even comment on? =)
>
It's on my list to look at, honest! As a general organizational note, are
you thinking of having a section of the Administrator's Guide for "one
pager" topics like this? Or are you thinking these are more chapters or
sections in something that feels like one overall document?
> - r
>
>
Craig
