Jon Stevens wrote:
>
> on 7/2/01 6:04 PM, "Christopher Cain" <[EMAIL PROTECTED]> wrote:
>
> > I
> > have no interest in Anakia, and quite frankly, as has been pointed out
> > very astutely by Costin, I have no interest in bothering with XML for
> > the purposes of documentation. I will produce HTML docs with my favorite
> > editor and call it a task adequately completed. Asking anything beyond
> > that will more than likely be more time and effort than I am prepared to
> > invest in simple documentation.
>
> I bet you will only use a certain brand of toilet paper as well.
Dunno. I let me girlfriend handle the tough decisions like that =)
> > In short, let us please continue and decide upon how to proceed.
> > Regardless of Jon's off-topic confusion, I would really like to know how
> > the community would like to see any documentation which I may
> > contribute.
> >
> > - Christopher
>
> That's good, cause I haven't seen you contribute anything so far, Ace.
>
> The answer is simple...
>
> <?xml version="1.0"?>
> <document>
> <properties>
> <author email="[EMAIL PROTECTED]">Christopher Cain</author>
> <title>Cain's Documentation</title>
> </properties>
> <body>
>
> <section name="Recent News">
> <p>
> Mr. Cain actually writes a bit of documentation instead of threatening us
> with the idea that he might do it someday if we are lucky.
> </p>
> </section>
>
> </body>
> </document>
>
> :-)
>
> -jon
Touche' ... that's fair. I have a small cache of docs that I never got
around to submitting, partly because they are install/config docs (and
the Tomcat install procedure has always been a moving target) and partly
out of sheer laziness. I will bring them up to date and cast them to the
dogs (tomcats?) before the next milestone.
There now at least three different approaches being tossed around. As
long as we come to one standardized solution, which I think is
important, I'm personally pretty doc-program agnostic. If the XML
solution being considered is as comparatively non-labor-intensive as the
rather insightful example above, then you might indeed be lucky enough
to have the gift of my documentation bestowed upon you =).
My point, badly made to be sure, was simply that it would be a good idea
to avoid over-engineering a doc solution. The more (most) people have to
try and learn an extensive DTD or templating system, the less likely
they are to bother. I have a feeling that there is an untapped wealth of
docs and notes sitting around out there, written by admins and users for
their own benefit in installation/configuration. The easier we make it,
the more contributions we will undoubtedly receive.
If a cohesive documentation system is decided upon, I would love to
start contributing. I personally agree with Pier that documentation is
easily as important than the product itself. I was very pleasantly
surprised to see a thread seriously discussing the issue of the current
"catch-as-catch-can" docs, and I got a little tweaked when it appeared
that it would flame out without resolution. For all my criticism of you
Jon, I do have to give you props on one thing. Of all the dev-list
bullies I know, you are the only one who can take as much heat as you
give, and do it with a smile. Plus most of the other bullies are so
hopelessly overmatched in verbal exchanges that it almost isn't any fun.
But you got flair, baby! =)
- Christopher
