"Geir Magnusson Jr." wrote:
>
> This is deja vu all over again. We should take one copy if this
> discussion (we had the same thing in Commons, and I am sure it happened
> everywhere else...), post it somewhere, and people can just submit
> article numbers or something rather than typing the same arguments over
> and over.
>
> "Yes, I know you feel [21], but [17-19,28]."
>
> It would be so much quicker...
>
> Christopher Cain wrote:
> >
> > being bothered with this thread are both completely irrelevant, Ace. 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.
>
> Documentation is just as valuable as the software...
I could not agree more. What I meant by "simple" documentation is that
I, personally, do not have to requisite expertise to write in-depth docs
on the various inner workings of Tomcat. Since there are a fair amount
of short docs on specific aspects, such as the NT service, running the
connectors in-process, etc., we should keep in mind that the frequency
of submissions of such "simple" documentation by users is inversely
proportionate to the complexity of the solution we choose. If I am Joe
User, and I put together some notes on how I managed to get a connector
configured under Windoze 2000, am I likely to try and learn a complex
DTD in order to submit it to the project, especially if I have a rather
demanding day job? Probably not. Am I likely to download a program,
learn it, and generate the right format? Probably not.
Now if a few people on the list are willing to take text and/or HTML
submissions and generate the "approved" format, then so much the better.
Since I have now opened my mouth and made a suggestion on what *others*
should do with their OSS time, I suppose I am more or less volunteering
to help up in that regard. But my point was simple to caution against an
over-engineered approach to documentation without a few people stepping
forward to help "own" Tomcat documentation. Otherwise it will only lead
to less documentation.
> > 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.
>
> Didn't you just say that you are going to do it in HTML and declare
> victory no matter what?
Actually, what I said was that I would declare it a "task adequately
completed." =)
What I meant to imply was that let's not make generating documentation a
class project. Like most non-critical software, at the end of the day it
doesn't really matter how many bells and whistles the solution provides
if no one has the inclination or the time to learn how to use a complex
package. We are all programmers, and the easier the solution the more
likely it is we will deign to actually bother with documentation.
My delivery was admitedly a little pointed and unclear because I was
having a little fun with Jon. But that's okay, he loves the abuse. =)
- Christopher
