tomcat-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Rob S." <rsli...@home.com>
Subject RE: Re: Vote on oustanding doc issues?
Date Mon, 09 Jul 2001 23:09:01 GMT
Preamble: <grumble> <grumble> =)

> I don't want to rush it.

Agreed, but at the same time, I'd like to decide sooner than later.  I'm on
co-op until August 24th, then I start full-time school again.  4 courses
doesn't leave a lot of room for TC docs.  Judging by the amount of progress
we've made recently (pretty much *zero* in over 10 days), I'll be graduated
by the time we figure out if Tomcat documentation needs a separate
repository.

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

Bundle the 3.2.x docs with 3.2.x and only have the 3.3 docs online ("latest
Tomcat release").  If you want the 3.2.x docs, get them with the binary or
whatever.  I certainly don't think we should keep old versions of
documentation updated.  I mean, why would updated 3.0 or 3.1 docs be useful?

Too much work, too little people wanting to do it.  I don't think anyone
would expect even a product company to update their documentation on old
versions.  The version of docs I, as a user, would expect to see 'shipping'
with 3.2.2 (if i want to download an older version of the container) is how
the docs looked at 3.2.2 ship time.

> 1b) Should Tomcat 3.x documentation be rolled together with Tomcat 4.x
> documentation?
>
> 1c) Should there be a separate CVS repository for Tomcat Documentation
> that is separate from jakarta-tomcat and jakarta-tomcat-4.0?

Depends on if there is something that should be factored out from the
documentation.  From what we've seen so far, aside from Craig's dev guide,
the answer is "not much".

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

I don't imagine anyone will want to take the task on of converting the
anarchical doc repository into the format is decided upon, or how we'll
generate anything useful for people to evaluate during that time.  So
someone writes in HTML, someone writes in DocBook, etc.  If I want to help
on different docs I have to figure out the viewing/editing mechanism for
each one?  Ugh...

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

Agreed, but the decision needs to be made.  I don't want to start discussing
something the moment we need it.

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

They're not being resolved, different questions are just asked over and over
again.

<grumble grumble> =)

- r


Mime
View raw message