cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Diana Shannon <shan...@apache.org>
Subject Re: [vote] micro-decision for docs: creation of cocoon-docs CVS module
Date Mon, 24 Mar 2003 12:48:01 GMT
   [ +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


Mime
View raw message