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