On Mon, 2 Jul 2001, Rob S. wrote:
> 1) People don't like to write docs, and for an open-source project, I'd say
> that's perfectly cool so long as those same people are willing to have a
> read through the docs after a major update to make sure they're coherent ;)
> For ours especially, to author them is a pain in the arse. You should just
> have to worry about content, but 70% of it is cruddy HTML formatting. Would
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.
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 ).
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.
And we'll certaninly have some flame wars about what DTD to use ( docbook
is the standard outside apache, stylebook is used in many apache projects
- which one should we use ? Many believe the first is too complex, but
some believe standards are important ). A good news - it seems AbiWord (
yet another editor ) can generate some basic docbook, and the gui is not
that bad ( amazingly, it can save as palm pdb, as well as latex ! ).
> 2) Why don't (a lot) of people read them? I dunno... I know that
> personally, I have a tendency to gloss over mounds of documentation, even if
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".
Speaking of notes, it would be very cool if we start a new directory and
colect the relevant mail from this list ( proposal, technical arguments,
etc). The list is full of crap, and extracting the usefull info is quite
difficult.
Costin
( answering mail rather than writing the C code :-(
