You are viewing a plain text version of this content. The canonical link for it is here.
Posted to docs@cocoon.apache.org by Bertrand Delacretaz <bd...@codeconsult.ch> on 2002/10/17 10:45:48 UTC
Cocoon primer, how about starting to write it on the wiki?
Hi everybody,
Steven rightly suggests [1] that we should write a "Cocoon primer" similar to
the "Forrest primer" [2].
I think we could create a page for this on the Wiki and start working on it
there. If ok, I will create the page with a skeleton document plans and some
initial content.
thoughts?
-Bertrand
[1] http://outerthought.net/wiki/Wiki.jsp?page=DocumentationTracksProject
[2] http://xml.apache.org/forrest/primer.html
Re: Keeping website docs in sync with *released* version? (was...starting
to write it on the wiki?)
Posted by 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?
Posted by 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?
Posted by 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?
Posted by 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?)
Posted by 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
Keeping website docs in sync with *released* version? (was...starting to write it on the wiki?)
Posted by 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: Cocoon primer, how about starting to write it on the wiki?
Posted by Diana Shannon <sh...@apache.org>.
On Thursday, October 17, 2002, at 05:12 AM, Steven Noels wrote:
> Now that I have commit rights, I did some looking around in CVS - I
> must say this branch stuff makes things hard to maintain.
It's especially disheartening when the cvs-HEAD docs build is broken (as
was/is the case as of last week[1]). Docs/content should depend on a
more reliable generation mechanism. I couldn't agree more that a
separate cvs branch/module will help matters.
>
> 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...
Perhaps I'm misunderstanding your suggestion, but this sounds like we'd
still need to maintain to separate sets of source documents, with a lot
of duplication between them. I don't see why we can't have a single set
of source docs, with the ability to generate different versions (2.1,
2.03, 2.04-dev, etc.) based on meta data or similar.
> Maybe I'm contradicting my own statements regarding this when Diana
> mentioned this, dunnow anymore.
It doesn't matter. I'm just glad we view the problem similarly now.
> I'm just throwing this up for grabs. Now that we have some more
> doco-oriented committers, maybe we have the momentum and the energy to
> continue the great work of Diana & David - but also the opportunity to
> rethink things.
Clearly Forrest represents a lot of this rethinking. You know David and
I have worked through multiple trial runs of using Forrest with Cocoon.
Problem was, a while back, it's seemingly alpha status (e.g. the
multiple threads about dropping document 1.1 dtd ) and my frustration
with the cvs branches made me hesitate in carrying out its incorporation
within the Coccon cvs.
Diana
[1] http://marc.theaimsgroup.com/?l=xml-cocoon-dev&m=103407963812713&w=2
Re: Cocoon primer, how about starting to write it on the wiki?
Posted by Steven Noels <st...@outerthought.org>.
Bertrand Delacretaz wrote:
> Hi everybody,
>
> Steven rightly suggests [1] that we should write a "Cocoon primer" similar to
> the "Forrest primer" [2].
>
> I think we could create a page for this on the Wiki and start working on it
> there. If ok, I will create the page with a skeleton document plans and some
> initial content.
>
> thoughts?
Go for it :-)
Good influences might be my Primer (ahum), and Jeff's
http://xml.apache.org/forrest/your-project.html.
I would like to give it a try, but it won't be for several weeks. I also
believe it should be something heading toward Cocoon docs CVS ASAP, so
maybe you could as well start directly in xdoc format. Wiki is good for
quick & dirty, but this should be quality whitepaper-ware.
Now that I have commit rights, I did some looking around in CVS - 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...
Maybe I'm contradicting my own statements regarding this when Diana
mentioned this, dunnow anymore. I'm just throwing this up for grabs. Now
that we have some more doco-oriented committers, maybe we have the
momentum and the energy to continue the great work of Diana & David -
but also the opportunity to rethink things.
</Steven>
--
Steven Noels http://outerthought.org/
Outerthought - Open Source, Java & XML Competence Support Center
stevenn@outerthought.org stevenn@apache.org
Re: Cocoon primer, how about starting to write it on the wiki?
Posted by Bertrand Delacretaz <bd...@codeconsult.ch>.
On Thursday 17 October 2002 17:34, Diana Shannon wrote:
>. . .
> Also, Cocoon is far more complex in functionality/scope than Forrest. A
> Cocoon Primer, as simple and elegant as the Forrest-related primers,
> seems more challenging. What would your outline be?
>. ..
I've written the outline at
http://outerthought.net/wiki/Wiki.jsp?page=CocoonPrimer.
It will be challenging to write, but I think it is invaluable in terms of
helping new users come up to speed with Cocoon quicker.
> What's the motivation for the new doc? A better user experience?
Currently a newbie needs to read (wild guess) 10-15 distinct HTML pages on
the website to understand what Cocoon is about and some of the things it can
do.
IMHO it would be good to reduce this essential info to two HTML pages:
"primer" explains what Cocoon is and roughly what it can do, and
"documentation tracks" is the entry point for more specific learning.
> Why do you think this doc needs to reside/incubate on Wiki?
Quite practical reasons: the idea is there but I don't have time right now to
write the document. I'm hoping that some people will contribute content or
ideas before someone finds the time to actually write the documents.
> Isn't the primer effort more a matter of
> editing or repurposing what we already have?
You're certainly right, but I think we can use the wiki to collaborate on
this editing or repurposing, with more chances of having comments from many
users early in the process.
Of course if someone finds the time to write the complete document soon, go
for it! I'd be happy to scrap the wiki pages anytime once there is something
better in the CVS (or if there is agreement that these pages aren't needed).
-Bertrand
Re: Cocoon primer, how about starting to write it on the wiki?
Posted by Diana Shannon <sh...@apache.org>.
On Thursday, October 17, 2002, at 04:45 AM, Bertrand Delacretaz wrote:
> Steven rightly suggests [1] that we should write a "Cocoon primer"
> similar to
> the "Forrest primer" [2].
It seems Cocoon has most of this content already although the it is
somewhat fragmented across multiple docs.
Also, Cocoon is far more complex in functionality/scope than Forrest. A
Cocoon Primer, as simple and elegant as the Forrest-related primers,
seems more challenging. What would your outline be?
What's the motivation for the new doc? A better user experience?
Why do you think this doc needs to reside/incubate on Wiki? My
understanding is the Wiki is strongest at generating *new* content not
necessarily editing existing content (particularly content that's not
wide-ranging in scope). Isn't the primer effort more a matter of
editing or repurposing what we already have? I just think that so much
can be to improve existing docs by restructuring (filling in holes,
rearranging, etc.) You wouldn't be starting from scratch, would you?
I'm not against your effort, but I'd like to know more...
Diana