Christopher Cain wrote:
>
> "Geir Magnusson Jr." wrote:
> >
> > 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.
I actually don't follow the logic here.
You said
"I have no interest in bothering with XML for the purposes of
documentation."
Writing XML docs is easy. For doing docs compatible with the 'implied'
anakia DTD, it's hardly different than HTML.
The nice part is that they can be managed and restyled.
> 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.
Again, I am not sure this parses for me. If you let people submit docs
in whatever randomly broken variant of HTML their HTML editor generates,
the submissions will be far less useful than just plain text.
So have a policy :
0) All documentation is appreciated.
1) If you can, submit docs using our XML DTD. It makes it easy to
integrate into the rest of the documentation. Here is a sample
template. Fill in the content section.
2) If you can't we still appreciate your effort. Please send us notes
and docs in ASCII text format.
In the beginning of the Velocity project, we had someone dedicated to
doing documentation. He wasn't technical, but was able to grok what
needed do be done, and styled and formatted whatever was offered. He
even watched the mail lists to get examples.
I would be someone might volunteer to be Minister of Documentation...
> 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.
Great!
> 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.
That's not how I read your post. However, I will assume now it was my
misunderstanding and leave it at 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.
> >
> > 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.
What you get if you don't is a mess.
> 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.
XML isn't that hard. Give it a whirl sometime..
> 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. =)
I am sure that's why he dedicates so much time to this.
geir
--
Geir Magnusson Jr. [EMAIL PROTECTED]
System and Software Consulting
Developing for the web? See http://jakarta.apache.org/velocity/
You have a genius for suggesting things I've come a cropper with!
