> >I'd rather keep the documentation together with the project. When I
> >(don't :) write the docs, I don't want to update two CVSes, we can give
> >access to whoever wants to write it...
>
> Many projects at jakarta may use tomcat and it would be great for them
> to be able to include all or parts of Tomcat docs without having to
> include the project itself ......
But that's really an organizational problem, not a documentation problem,
no? I guess I'm not sure how creating a new project is going to get people
to write or read documentation? =)
What are the 'problems' with documentation?
1) Developers don't write them in lieu of coding.
2) Users don't read them
3...) ?
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
developers write more docs if they didn't have to go through the pain of
HTML? I noticed that the Struts docs are in XHTML using a single style to
render them all. I wonder if we could toss a small front-end over something
like that, that allowed you to do like 90% of the doc writing work via the
web. Any crazy custom formatting or anything and you'd have to edit the
.xml directly. Dunno, just brainstorming here... The TC4 docs are part of
a web-app already (re: ROOT/docs). I'd be extremely interested in doing
something like if everyone thought it was a good thing.
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
it's Good For Me(tm). Hell, it works for computer games, why not Tomcat?
This is why I proposed we break the docs up into more bite-size chunks. I'm
sure there are lots of other 'problems' with them, but we receive very
little feedback aside from "TOMCAT SUCKS!" so it's hard to do anything about
it =)
Thoughts?
- r
