tomcat-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Rob S." <>
Subject RE: [PRE-PROPOSAL] jakarta-tomcat-doc sub-project : WAS: [TomcatDocu mentation Redactors To Hire]
Date Mon, 02 Jul 2001 16:14:28 GMT
> I'm not sure I understand that. There are plenty of HTML editors, and 99%
> of the people on this list know a bit of html. Nobody asked for "good
> looking" documentation or cool formats, the content is missing.

Agreed, but using Note/Text/Whatever/Pad is what the majority of people end
up using because WYSIWYG editors have a tendency to butcher the resulting
HTML for the next poor sap to come along and edit it.  <insert years of
notepad versus wysiwyg editors debate>.

As well, nobody's *asking* for good looking docs, but if someone's willing
to put in the time and effort (e.g. myself), what else can it do other than
help? ;)  It's possible to have better-than-average-looking docs with a few
well-chosen colours, etc. without burdening the build with images.

> We do need to reorganize the documentation and update it - and I agree
> with moving it part of a /doc webapplication ( instead of a doc directory
> - we can leave only the minimal README in tomcat/doc telling how to start
> tomcat in basic mode and look at the /doc webapp ).

I fully agree with the reorganization since right now there isn't really
any - aside from appdev having its own subdirectory.  I'm not sure I
understand the reasoning behind making the docs part of the ROOT (or /doc)
web-app.  I imagine to make them accessible from the default Tomcat
homepage?  How un/important is that?  Either way, like I mentioned before -
organization decision, not a doc author's =)

> But I'm not sure it would be a good idea to use something else than
> HTML ( I actually think it would be a very bad idea at this point ). Then
> people will also have to worry about learning a new set of tags ( whatever
> dtd we use), not only about content, editors will be out of question,
> we'll have to spend time working on the transformation, etc.

Right now if you look under the Struts repository, you'll see that all of
the documentation is *.xml, and I imagine the build is responsible for the
transformation...  I guess we'll have to talk to them to see how all of that
is working out - what's the motivation?

> My opinion - the documentation is not very well organized, I guess someone
> should "own" it and organize it as a book or as a standalone
> webapplication. Right now there are mostly a bunch of "notes".

Yep, very much agreed.  There needs to be some glue for all of the separate
docs floating around, rather than combining them all into one big "User's

> Costin
> ( answering mail rather than writing the C code :-(

...or writing docs!  j/k of course =)

So in a nutshell, here I am, raring to go on documentation.  I guess I'll
work on the TC4 INSTALL ??? to describe how to get the container up and
running to view the docs.  I'm really waiting for some guidance =)

- r

View raw message