Keeping website docs in sync with *released* version? (was...starting to write it on the wiki?)

[Bertrand Delacretaz <bd...@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.

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

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

-Bertrand

Re: Keeping website docs in sync with *released* version? (was...starting to write it on the wiki?)

[Nicola Ken Barozzi <ni...@apache.org>]

Diana Shannon wrote:
> 
> On Thursday, October 17, 2002, at 06:19  AM, Bertrand Delacretaz wrote:
...
>> 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?

Both; usually WIP docs are related to WIP functionality, anyway it's a 
simplification.

Over @the Ant dev list, there have been already discussions about users 
complaining they wanted the "release" version of the docs, while others 
wanted only CVS version.

Personally, I'm totally convinced we need both.

Or keep the CVS version up front and link to the releases versions, or 
the opposite.
But having WIP on the main page is really bad...

>>  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?

+1, as I suggested

-- 
Nicola Ken Barozzi                   nicolaken@apache.org
             - verba volant, scripta manent -
    (discussions get forgotten, just code remains)
---------------------------------------------------------------------

Re: Keeping website docs in sync with *released* version?

[Bertrand Delacretaz <bd...@codeconsult.ch>]

Hi Diana, thanks for the comments!

>. . .We'd need to remember to
> provide redirects (from old URIs) in a major way.

yes ok, we'll need this.

>. . .Beta or alpha docs. Alpha should be marked differently...

I used "beta" as a generic term. What's important IMHO is to use terminology 
that is understandable by Joe User (who might have no clue what CVS or WIP 
is). 

But yes, being able to categorize (parts of) documents as "alpha, beta, 
release" is certainly good if the effort is not too big for authors. 

In a document production system that I helped design we use a 
"publish-status" attribute on all block-level elements, which is inherited by 
inner elements from outer elements at publication time and has values like 
"draft", "beta", "release", etc.

Maybe something along these lines should be added to the xdocs DTD to 
generate these categorizations?

>. . .I think CVS is great for code, but it really gets in the way with docs
> management....

Coming from a coding background, maybe I tend to use CVS too much? I'm open 
to your ideas of course, keeping in mind the "external requirement" of not 
confusing users with docs that are out-of-sync with the released version and 
not marked as such.

What scares me if we're not using CVS tags is having to revisit every 
document on each release, to move "alpha" elements to "release" and so on. 
Hopefully you or someone has a better idea...

> If you have time, you should check out how much Forrest can do in all of
> the above areas.

I did this morning - Forrest looks great to me, and I see the potential much 
better now.

-Bertrand

Re: Keeping website docs in sync with *released* version?

[Diana Shannon <sh...@apache.org>]

On Monday, October 28, 2002, at 04:38  AM, Bertrand Delacretaz wrote:

> Here's my proposal regarding publishing both release +  beta docs on 
> the web
> site:

Thanks for your proposal, Bertrand.

> -The website docs (reference-doc/release?) reflect the latest release of
> Cocoon, although each document might have been updated since the 
> release.

I agree, better URI space will be very helpful. We'd need to remember to 
provide redirects (from old URIs) in a major way.
See:
   http://marc.theaimsgroup.com/?l=forrest-dev&m=102390892524750&w=2

> -Beta docs are available in a distinct path (reference-doc/beta?) on the
> website, they reflect the current CVS HEAD and are *automatically* 
> marked as
> such during HTML docs generation.

Beta or alpha docs. Alpha should be marked differently (more stern in 
tone/appearance) than beta. For example, see the language (not style) 
used here:
   http://xml.apache.org/cocoon/howto/xmlform-wizard/howto-xmlform-
wizard.html

> -Docs are generated based on CVS tags, for example the following 
> scenario
> could be used to generate the complete website ("build website-docs"):
>
> 1. checkout CVS docs with tag RELEASE_DOCS, build "release" website 
> pages
>
> 2. checkout CVS docs from HEAD, build "beta" website pages, option 
> tells XSLT
> transforms to include "beta docs" warning

Maybe, but I'd prefer to at least try to have a single set of docs for 
the 2.x Cocoon with version info included as meta data or similar. I'm 
going to explore doing this via Forrest asap. I had some ideas for 
accomplishing this months ago, but didn't get it finished.

> Maybe a third category/CVS tag is needed for "current info" pages which 
> have
> no relation to the version of Cocoon.

I think categorizing docs via cvs tag is a bit limiting. There are so 
many ways we could mix and match groups of docs beyond these three tags. 
I think CVS is great for code, but it really gets in the way with docs 
management. In fact, I think so much of the problems we face have their 
roots in the fact we are treating docs more as code, much less as 
content. I truly love to write and edit, but I have to confess that I 
have a **major** aversion to working with our docs, the way our system 
is set up right now.

> I don't know much about Forrest yet, but this can certainly be automated
> using ant. It has to be automatic, we don't want to maintain all this
> manually.

If you have time, you should check out how much Forrest can do in all of 
the above areas.

Diana

Re: Keeping website docs in sync with *released* version?

[Bertrand Delacretaz <bd...@codeconsult.ch>]

Coming back to this discussion after some quiet time...

Diana, I agree that docs need to be revised, my idea of completely freezing 
them at the point of the last release was a bad one.

Also, I understand that the current way of updating the web site would make 
it very hard to maintain two separate sets of docs manually.

Hopefully the move to Forrest will improve this, but in the meantime we can 
maybe agree on the goals, even if we cannot reach all of them right 
now?

Here's my proposal regarding publishing both release +  beta docs on the web 
site:

-The website docs (reference-doc/release?) reflect the latest release of 
Cocoon, although each document might have been updated since the release.

-Beta docs are available in a distinct path (reference-doc/beta?) on the 
website, they reflect the current CVS HEAD and are *automatically* marked as 
such during HTML docs generation. 

-Docs are generated based on CVS tags, for example the following scenario 
could be used to generate the complete website ("build website-docs"):

1. checkout CVS docs with tag RELEASE_DOCS, build "release" website pages

2. checkout CVS docs from HEAD, build "beta" website pages, option tells XSLT 
transforms to include "beta docs" warning

Maybe a third category/CVS tag is needed for "current info" pages which have 
no relation to the version of Cocoon.

I don't know much about Forrest yet, but this can certainly be automated 
using ant. It has to be automatic, we don't want to maintain all this 
manually.

Authors can update the release docs easily by moving the RELEASE_DOCS CVS tag 
to the appropriate version of the document. 

Comments?

-Bertrand

Re: Keeping website docs in sync with *released* version? (was...starting to write it on the wiki?)

[Diana Shannon <sh...@apache.org>]

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