cocoon-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Diana Shannon <>
Subject Re: Stages of Forrest Transition
Date Sun, 23 Mar 2003 15:56:46 GMT

On Sunday, March 23, 2003, at 10:39  AM, Jeff Turner wrote:

> On Sun, Mar 23, 2003 at 09:48:47AM -0500, Diana Shannon wrote:
>> How should we transition? How about:
>> 1. Set up live protoype Forrest environment (now happening)
>> 	- work out remaining configuration issues
>> 2. Set up separate Cocoon docs repo(s)
>>    - decide what the repo will include (simply docs and/or tools)
> Do you mean, commit a Forrest binary into cocoon-docs CVS?

Not what **I** want, just what some were suggesting earlier. Also, doc 
tools can include tools that aren't necessarily Forrest.

> Why not just
> make a snaphot available for download, or let people run 'cvs update -r
> stable' on Forrest to get a known-working version?

I'd vote for this myself.

>>    - copy both 2.1 and 2.0 docs and associated files into separate
>> modules/branches/repos. Maintain "old" doc build capability, as
>> currently functioning, in 2.1 and 2.0.
> Sounds like a lot of work.. why go to all that effort to keep the old
> system alive, if the Forrest system is 95% working?

Just during a transition. To keep doc builds functioning for users. To 
avoid down time during v11 transition.

> Also, having XML in a separate cocoon-docs module is likely to trigger
> the "out of sight, out of mind" syndrome.

I hope this isn't true. I also believe it's an overgeneralization. We've 
had this debate a lot. I had the impression that consensus is moving 
toward supporting a single docs cvs.

> Right now, when I change some
> code (say, rename DefaultsMetaModule to DefaultsModule), I can simply
> grep cocoon-2.1 and find all references to the old class in code *and*
> docs, and update them.  With a separate module I'd probably forget, or
> forget to 'cvs up' it.

Well, some of us believe a single docs cvs, which can produce 2.0 or 2.1 
docs will be even better. In your above-described scenario, you'd also 
"forget" to update cocoon-2.0 (if necessary) since it's now in a 
separate repo. That "forgetfulness" issue didn't prevent the repo 
separation of code.

Think about a wiki/html editing system which writes to cvs. Wouldn't you 
want a separate docs cvs for that? As far as docs which depend on 
specific files in a  code cvs (e.g. jars.xml), Forrest simply needs to 
know where such cvs repos live (locally or via view-cvs or similar).

>>    - setup docs build capability for user docs and web site
>>    - add static documentation (built by cocoon-docs repo with Forrest)
>> to both 2.0 and 2.1 repos
> ?! Do you mean, commit 10mb of generated HTML/PDF to cocoon-2.1?  I hope
> not :)

As a matter of fact, yes, with or without pdf. Most of the cvs-based 
projects I download have static doc files in their cvs, not dynamic 
doc-generating capability with doc source files. Are you saying this 
practice is "old school"? I personally **really** like to simply double 
click a doc file to get started instead of figure out how to build the 
docs first.

And/or, we could make doc set snapshots available, as we do now for code.


View raw message