On Mon, 30 Jul 2001, Rob S. wrote:
> > 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...
>
I don't contemplate a change in the current <document> / <body> /
<section> / <subsection> hierarchy, so you can start there. Arbitrary
HTML can be nested inside, as long as all the tags balance in an XHTML
style (i.e. <p> ... </p>, use <br/> to create a <br>, and so on).
Adding specific styling tags for kinds of tables should probably wait
until we choose the final technology. Interestingly, the same discussion
is going on over at xml.apache.org about how they generate their web site,
so maybe we'll be able to leverage the results of their thoughts (and they
probably know a *lot* more about XML than we do :-).
> > 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 =)
>
Yep ... you'll be able to test out my new "BUILDING.txt" instructions :-).
The snapshot of the generated docs is also online at:
http://jakarta.apache.org/tomcat/tomcat-4.0-doc-exp/index.html
> > 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?
>
That sounds like a good approach. Once in a while, we'll run into
multi-page major topics, but that is probably fairly rare.
> 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
>
>
Craig
