cocoon-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Steven Noels <stev...@outerthought.org>
Subject Re: [vote] micro-decision for docs: creation of cocoon-docs CVS module
Date Mon, 24 Mar 2003 08:40:19 GMT
On 24/03/2003 8:29 Andrew Savory wrote:
> 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


Mime
View raw message