tomcat-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Alex Chaffee <>
Subject DOC: Re: Vote on oustanding doc issues?
Date Mon, 09 Jul 2001 22:04:12 GMT
On the topic of a new mailing list:
I think we can do the next steps inside the tomcat-dev list or on our 
own. (BTW, let's use "DOC:" as a prefix so it's easier to scan for new 
messages.) I want to do this in full view of the rest of the community, 
mostly so they can see what's going on and volunteer to contribute.

(Martin's notes-gathering list is a good idea, but I think a bit 
premature, given issues like what the topics are and what format they 
need to be in. I definitely don't want substantive discussion to happen 
on his lists (see prior para.))

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?

I don't want to rush it.

> 1) Tomcat documentation per-project or in a single repository?

This is actually three separate questions, and I don't think any are 
quite ready for a vote yet:

1a) Should Tomcat 3.2 documentation be rolled in together with Tomcat 
3.3 documentation for a single, up-to-date, source base, whose release 
cycle will be independent of the release cycle of Tomcat?

1b) Should Tomcat 3.x documentation be rolled together with Tomcat 4.x 

1c) Should there be a separate CVS repository for Tomcat Documentation 
that is separate from jakarta-tomcat and jakarta-tomcat-4.0?

(Currently, there's a src/doc subdirectory in the jakarta-tomcat 
repository that would work just fine (especially if the answer to 1b is 
"no.") OTOH, it might be nice to get a fresh slate, our own build.xml, etc.)

(Personally, I'm leaning towards yes on all 3, but I'm not quite sure.)

> 2) What is the format (XML, *Book, HTML, etc.) of the documentation source?
> If XML, what DTD?

I propose that we do *NOT* try to answer this yet, or maybe ever. 
Instead, I propose anarchy: that the Table Of Contents be maintained in 
a convenient text-editable format. It will contain links to doc files 
(sections or guides or chapters) that are files in whatever format 
they're in. I imagine that it will eventually be most convenient to use 
Anakia, but for now, it means that we don't have to worry about 
rewriting useful docs that are already in HTML.

Organizing the TOC and and assigning volunteer authors to write parts is 
much more important than file format right now.

> 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.

We can work on the TOC independently of resolving those other issues.

Alex Chaffee             
jGuru - Java News and FAQs
Creator of Gamelan       
Founder of Purple Technology
Curator of Stinky Art Collective

View raw message