cocoon-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Piroumian Konstantin <KPiroum...@protek.com>
Subject RE: Keeping website docs in sync with *released* version? (was... starting to write it on the wiki?)
Date Thu, 17 Oct 2002 12:04:45 GMT
> From: Bertrand Delacretaz [mailto:bdelacretaz@codeconsult.ch] 
> On Thursday 17 October 2002 11:12, Steven Noels wrote:
> . . .
> > maybe you could as well start directly in xdoc format. Wiki is good 
> >for  quick & dirty, but this should be quality whitepaper-ware. . . .
> 
> Agreed, only that currently I have very little content for these new 
> documents, so I will try to create the pages on the wiki and 
> see if people 
> bring in ideas and content.
> 
> >. . .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.

There can be several solutions to this, e.g.:
	- using a special 'version' or 'since' marker attribute in documents
to be able to filter content based on version or to generate some
notification for users (markers can be used for the whole document or only
for particular sections).
	- using separate paths (as suggested below), but having complete
documentation for both versions: release and the CVS HEAD. Just like it is
done in other Jakarta projects, e.g. Struts 1.0 and 1.1, Tomcat 3.x/4.x,
etc.

> 
> 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).

Sometimes it is needed to update docs more frequently even for the released
version - documents can have bugs too and they need patching ;)

> 
> b) Publish the CVS versions of the docs on alternate path 
> (xml.apache.org/cocoon/work-in-progress or 
> xml.apache.org/cocoon-cvs) with a 
> suitable warning on all pages ("this relates to the unstable 
> CVS version blah 
> blah...").

Yes, something like this would be better.

Regards,
  Konstantin

> 
> -Bertrand
> 

Mime
View raw message