cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Stefano Mazzocchi <>
Subject Re: [vote] micro-decision for docs: creation of cocoon-docs CVS module
Date Mon, 24 Mar 2003 13:23:43 GMT
Diana Shannon wrote:
>   [ +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 hear you, Diana. I hear you.

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

This is true.

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

This will reduce the ability for people to generate documents from being 
offline, but since we will include a prebuilt documentation in our 
distribution, this doesn't really matter since users won't be making doc 
changes anyway.

As for committers, it's not too much to expect them to have downloaded 
all modules.

>> - 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).

I think this is the main point and I would like to give some thoughts.

I don't expect 2.0 to live long after 2.1 is out. There is no reason to. 
If there is something back-incompatible, it's a bug and it will be 
fixed. Nobody should have problems in switching to 2.1 and if they did, 
we fix their problems because we (and them) *expect* an easy migration.

At that point, there will be only *one* repository for docs and it will 
live close to the code it belongs to.

In the future, i would like block-specific documentation to remain 
inside the blocks. Everything should remain as close as possible to the 
code: javadocs, tests, metadata in general even documentation, 
configurations, avalon roles, block metainfo and what not.

creating a single docu repository is, IMO, a very dangerous road because:

1) it gives a perception that documents are maintained by somebody else. 
This perception is already here and it's probably my fault and this is 
causing pain and trouble to many people. I want this to be fixed in 
order for the process to be more scalable.

2) it has a short-term impact on a short-term problem that is an 
evidence of a much bigger problem: our inability to do faster releases. 
we should design the entire system to allow us to make faster releases 
and this should be our goal, even if potentially disruptive for the 
short term.

So, at the end, since 2.0 is going away, we should plan for 2.1 with 
full steam and plan for that, living the transition as a potential 
teacher for future need.


View raw message