> 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.
I prefer [DOC] btw.. replying to a doc issue with DOC: removes the DOC:
entry. (at least in outlook).
> (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.))
The lists are not for discussion and especially not these discussions.. They
should contain notes! Good idea, a hey, mail to one of the lists (you don't
have to be a member).
The format needs to be discussed indeed. My "proposal" on that wasn't really
usefull and too complicated.
> > on these two things? Are we ready to do that yet?
>
> I don't want to rush it.
Better do it correct the first time.
>
> > 1) Tomcat documentation per-project or in a single repository?
> >
>
> (Personally, I'm leaning towards yes on all 3, but I'm not quite sure.)
I agree completely. Don't think we must start this in a current cvs root.
> > 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.
The main parts and main chapters in seperate subdirs at first?
Generating a default output at a certain point is not too bad though. But we
have to be open enough for people who want to convert this to eg man pages
or a nice pdf.
> Organizing the TOC and and assigning volunteer authors to write parts is
> much more important than file format right now.
I already volunteerd for the gathering notes ;)
> > 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.
As long everything is stays flexible enough, we don't want to spend 80% of
our time in generating docs in whatever format. In the beginning we probably
will only be complementry to current documentation until we are grown up
enough to be the source for documentation on tomcat releases. This leaves
room for experimenting with what works best.
A vote on a seperate mailinglist for discussing doc issues would be
appreciated though. It's getting a lot of discussion already and this will
grow in the near future I think (and hope..). This way we don't miss any of
the important non-docs specific stuff.
Mvgr,
Martin
