"Geir Magnusson Jr." wrote:
>
[snip]
Most of this was under the assumption that there would be no one
volunteer to dedicate additional time and energy in a little cabal of
people to take the lead on organizing and standardizing Tomcat
documention. Since I have now gone from, "Bah! Don't pester me about
learning Anakia or any other damn thing for simple docs," to, "Cool,
let's organize and standardize this bad boy," and since you are offering
to devote time as well, all my previous grumblings are officially
withdrawn. Under an organized approach, which I will damn well help out
with, I can live with almost any solution.
> > 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...
You and I are in complete agreement here. I had considered that people
would hand-code the HTML, but maybe you're right in that that might be
too much to hope for. God help us all if people start submitting Front
Page-generated docs!
I think your policy suggestion makes perfect sense. Again, as long as
there are people willing to help out with accepting/converting any user
docs instead of simply telling people of varying skill levels to go
learn Anakia or whatever, my reservations about the complexity of the
approach vanish. My statements about keeping it as simple as possible,
possibly HTML, were under the assumption that no one would continue to
be "in charge" of documentation. I just don't want to see it get any
harder for docs to get included in Tomcat ... it's already pretty
hit-and-miss as it is.
> XML isn't that hard. Give it a whirl sometime..
I have a pretty reasonable amount of experience in XML. It wasn't really
a question of knowledge, it was more a question of how much overhead it
would add. I had visions of trying to install and configure some
screwball display parser for half a day just to preview my documentation
in order to get it accepted. Since it appears that I have unwittingly
placed myself into the newly-forming "Ministry of Documentation",
however, I guess that's not much of an issue anymore. =)
Seriously, though, I think your proposal makes sense. I will certainly
assist in this new, more organized approach to TC documentation. As I
said, I have no real opinion about which solution to go with. XML, HTML
(no FrontPage!), DHTML, XHTML ... whatever, I'll let you guys sort it
out. I kinda liked the idea of having it set up as a new context and
installed along with Tomcat, though. That would be pretty hip, and the
idea has merit.
- Christopher "His-love-is-real,-but-his-documentation-is-not" Cain
