[ +1 ] creation of cocoon-docs module [ ] docs should stay in src/documentation of the code tree module(s)
I feel strongly about this, give the past year of my watching cvs commits. The fact remains that many committers don't update both doc branches when committing docs. If someone needs **facts** check out the cvs thread when we were all updating the cvs committer list as active/inactive/emeritus/etc. It's quite revealing to see who updated release branch and who did not. It's also a fact that a vast majority of our docs are identical in cocoon 2.0 and 2.1 branches. The idea of a single docs module is supposed to make it easier and more obvious for committers when committing doc patches.
So, if this fails, we need some kind of discussion how to encourage people to be more thoughtful when committing. I'm not going to spend the next year of my commiter life syncing docs in code repos.
I also want to respond to some of Jeff's concerns below.
On Monday, March 24, 2003, at 04:13 AM, Jeff Turner wrote:
Please cast your vote:
[ ] creation of cocoon-docs module [+1] docs should stay in src/documentation of the code tree module(s)
Because:
- With a separate cocoon-docs module, I don't see how the various code-related files (status.xml, jars.xml) are obtained.
Locally, referenced via a path set in a configuration file. If code repos aren't available/downloaded, info can also be looked up online via a parsed view-cvs data. Still, I don't think it's too much to expect from committers, to have all three repos.
- Making a separate doc module kills outright any future efforts to generate docs directly from code (e.g. a component manual).
Not at all. There's no reason a doc-generating mechanism can't look up or gather info/files from other cvs code repos during a docs build.
- I think that by default, doc changes should only apply to one codebase
(2.0 or 2.1). There are many differences that are *meant* to be there,
that could get lost if 2.0 and 2.1 docs are generated from a common
source.
Not true in our current case. Of course, this may evolve to be the case down the road, but as I said above, most docs at the present time are identical (exceptions: install, catalog, some how-tos, some webapp pages).
Diana
