cocoon-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Diana Shannon <shan...@apache.org>
Subject Re: Keeping website docs in sync with *released* version? (was...starting to write it on the wiki?)
Date Thu, 17 Oct 2002 16:01:40 GMT

On Thursday, October 17, 2002, at 06:19  AM, Bertrand Delacretaz wrote:

>> . . .I must
>> say this branch stuff makes things hard to maintain.
>> Possible alternative: have a separate module/directory in HEAD with a
>> subdirectory per version (2.0.x and 2.1-dev) instead of using 
>> branches...
>
> I think CVS branches are fine for evolving the docs, but maybe we 
> should not
> update the *website docs* until a new version is released? It must be 
> really
> confusing for newbies to read docs on the website and not be able to 
> use the
> features in the version that they have.

I disagree. I think it's important to publish well-written docs, even if 
they are about alpha features. We made it a policy to have all such docs 
clearly marked to avoid user confusion. If other efforts make it less 
confusing (URI space, visual clues, etc.) then I'm 100% behind them.

Here's some advantages to publishing such docs:
1. Helps to recruit/motivate new writers. The docs we need most are 
probably going to be those about alpha or beta features. However, if 
there is a huge time delay between writing docs and a release 
(publishign), then the motivation for writers diminishes. For example, 
many doc writers will probably be one-time contributors. Perhaps some 
will be motivated by a need to be published in a visible way. Publishing 
quality docs on the web site rewards their effort.

2. Improves visibility of certain Cocoon functionality. Not *all* 
components/code in an alpha version are alpha. Writing a doc about a 
component in an alpha version doesn't mean the component itself is alpha.

3. We have some exciting stuff happening in Cocoon. Look how much 
attention and interest the portal and XMLForm components generated they 
had docs. I think making these documents available on the web had an 
overall positive effect.


>
> I'd suggest the following, but don't know how hard this would be given 
> the
> current xml.apache.org website mechanisms:
>
> a) Default version of website docs stays frozen as it was when the last
> release was done (except the "news" pages).

I disagree. Why should it be frozen? To make it easier on committers? I 
think this might discourage patching and updating docs.

> b) Publish the CVS versions of the docs on alternate path
> (xml.apache.org/cocoon/work-in-progress
What does works-in-progress refer to? The code or the docs?

>  or xml.apache.org/cocoon-cvs) with a
> suitable warning on all pages ("this relates to the unstable CVS 
> version blah
> blah...").

Warnings already exist. Some docs with 2.1 content still lack them, 
though.

How would you implement the build? Isn't it better to add this 
functionality to Forrest first?

Diana



Mime
View raw message