> It's not formally resolved, but it's time for us to just "do
> something" instead of just talk about it.
Agreed. Keeping things HT/XML with an agreed-upon set of tags sounds good
to me. I'll do that, keeping in mind the example docs (e.g. index.xml).
Soon tho', we'll have to decide on a more extended set of tags to do things
like tables and whatnot...
> 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.
It's going to have to wait until tonite after I can finish setting up my
local machine. I only checked out /jt4 last nite and apparently need a few
more things before that task will complete successfully =)
> 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
Just the "running multiple" one, that I'll convert to the format if someone
gives it the ok and touches it up a little bit =)
> 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
I had some thoughts about an introduction (see below).
> 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.
Agreed. If the reference stuff is pretty much done, I don't mind helping on
the conversion once we decide on a structure. As well, that leaves the
goal-oriented approach to be done, so we'll need a list of goals to start
catering to. I think having the docs organized (at least partially) by
goal, would prove a much more rewarding experience for users. This is
contrary to the, "teach them everything and have them figure it out
themselves" approach. Apache was so frustrating that way. I kept having to
search the newsgroups to find out how to do seemingly common and simple
things =/
> 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?
No worries, you've got code + organizational bits to do and I think the code
is more important anyways. I just wanted to make sure it didn't slip
through =)
I'm not sure about how to break up the sections into individual files or
documents yet. I thought for now, we'd keep things one-file-per-major-topic
and as we agreed on what goes where, deal with moving things around?
There still needs to be some sort of introduction to the container. Rather
than clutter up the docs with background information at every step, I think
we should try to centralize this, a prerequisite of some sort, to continuing
on with the documentation. Not too long as to make people skip it, but
enough so that we don't have to explain what a Context is every time we use
the word. I think the "Getting Started" section should be the place for
this, and if I knew how to use any other gfx tool than Visio, I would make a
pretty picture explaining the different routes through the docs. Maybe I
can get my gf to do it for me ;)
- r
