[ +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.
Ok.
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.
Stefano.
