Not a committer, but:
Nearly there! ;-)
On Mon, 24 Mar 2003, Steven Noels wrote:
Please cast your vote:
[+1] creation of cocoon-docs module [+1] docs should stay in src/documentation of the code tree module(s)
(where +1 for docs in src/documentation is for static docs)
Could you expand on 'static' docs, please?
I was lazy this morning, so I'm glad relevant points are iterated below.
So, here it is: discussion on cocoon-docs repository.
As I see it, there are the following pros/cons:
PRO:
1) Keep all documentation in one place (rather than split across two repositories as now), optionally with tools required to build it. Keeps documentation concern separate from code.
2) Allows people to work on documentation without needing a copy of Cocoon CVS (which implies optional cocoon-doc-only committers, although I'm not sure if this is good/required). Focuses attention on documentation as an entity.
3) Allows merging of 2.0/2.1/... documentation into a single base (not possible if documentation is kept in version-specific code repository).
<agree/>
CON:
1) Out of site, out of mind. If it is split, will developers forget to update the docs?
As I said, already the code repo is split across two modules, so anybody working on both 2.0.x and 2.1 versions has already two sandboxes, adding another one shouldn't be too hard.
2) If you checkout the code, you don't get a copy of the documentation.
People 'checking out' (= investigating) the code should download a source distribution. We've been requiring people to live off CVS checkouts already for too long. People 'CVS checking out' should not mind checking out another module.
In my mind, pro 3 is enough to swing it, but I'd like a solution to con 2 as it worries me. Perhaps the answer to con 2 is to include the static snapshot not within cocoon-docs but within cocoon-2.0/cocoon-2.1? So then you get a copy of the software with a static copy of the docs, and can check out doc cvs if you want to build it dynamically?
Ah - 'static' == generated...?
</Steven> -- Steven Noels http://outerthought.org/ Outerthought - Open Source, Java & XML Competence Support Center Read my weblog at http://blogs.cocoondev.org/stevenn/ stevenn at outerthought.org stevenn at apache.org
