I was out of town for the holiday, so I have just read almost all of
this ex post facto. It looks like there are quite a few people, myself
included, willing to devote an appreciable amount of time to an informal
new group of "doc wrangers." When I originally jumped into this thread
early on, I had no idea that there were so many people ready to help
out. That the Tomcat list has so many people truly interested in
providing users with extensive and well-organized documentation only
speaks to the quality of the Tomcat developer community. Hell, most OSS
projects would be arguing over whether there would be enough internal
effort to even warrant a separate docs sub-project. The fact that this
is a foregone conclusion with Tomcat, and that we are actually debating
whether or not it makes logical sense, is really quite impressive when
you stop and think about it.
Anyway, I agree with Rob. I would like to see a committer bring at least
#1 to a vote at this point. That way we can at least get the directories
in place, where we can then start shuffling all existing docs into an
organized location (or locations) and go from there. Alex has graciously
agreed to be the current Czar, and based on his work at jGuru, I think
we should *definitely* take him up on that. He and Rob seem to have a
sensible Master Plan(tm) with the TOC. With #1 out of the way, at least
people can start sending in whatever is out there. Once our fearless
Czar consolidates that, we'll can get a good idea of where we stand. The
rest (doc format, to webapp or not to webapp, fine tuning the TOC, etc.)
can follow later. I think that once we have something tangible (the
repositories), everything else will start to take shape quite nicely. A
vote on #1 will also, through the resulting +1's vs. +0's, give us an
idea of exactly how many contributors this new cabal will have. The more
people who answer the roll call, the fancier and more extensive we can
get when dicussing the TOC.
Regards,
Christopher
"Rob S." wrote:
>
> Not to be pushy or anything, but I'd like to get these settled quickly so we
> can get down to writing some docs =) Does a committer want to call a vote
> on these two things? Are we ready to do that yet?
>
> 1) Tomcat documentation per-project or in a single repository?
>
> 2) What is the format (XML, *Book, HTML, etc.) of the documentation source?
> If XML, what DTD?
>
> Okay, you can't really vote on the second I one I guess =) Hmm... what to
> do? Personally I'd like to use something XML-like, but close to HTML. It
> would require less documentation (re: tags) and less work than HTML to
> author docs, meaning hopefully more people would do it, more often. If
> that's Anakia, whatever. If it's XML with some other DTD, whatever.
>
> Once we know these two things, we can get to work. Of course there will be
> discussion on these points, but I'd like to bring them to a close sooner
> than later, so we can keep moving on with things like the TOC.
>
> - r
