cocoon-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jeff Turner <>
Subject xdoc -> wiki documentation (Re: documentation in separate cvs module or block)
Date Wed, 19 Feb 2003 07:45:49 GMT
On Wed, Feb 19, 2003 at 03:11:44PM +1100, David Crossley wrote:
> Diana Shannon wrote:
> > I find it a PITA to have to update my HEAD **and** release cvs
> > branches for simple document updates. It's frustrating to have
> > doc updates dependencies on a HEAD branch that doesn't reliably
> > build. I think a separate CVS branch/block/module would be a
> > definite improvement of the existing situation, but I still think
> > Wiki should remain the way a majority of people contribute/patch
> > docs. In fact, I think we should consider moving all existing
> > Cocoon docs straight to Wiki, so people can patch them there.
> > I proposed it early, when Cocoon's Wiki started, but I backed
> > off, given the fact it looked like a way to run around Forrest --
> > which I didn't want to do. However, now with Wiki's increasing 
> > integration to Forrest (and Steven's ideas of converting wiki
> > docs via site.xml or similar), it makes increasing sense to me.
> Will people be able to do both ways - traditional patch/create
> xdocs in cvs, or via the Wiki?

With Chaperon integration, the next version of Forrest should be able to
handle cwiki and xdoc formats equally well.

> Online editing might be okay for people in well-connected countries.
> However, for the rest of us, working online via dial-up modem through a
> clumsy web interface is not productive.

Well, with the wiki, you click 'edit', make your change, click 'save',
and that's it.

With CVS, you have to:

 - Download a CVS client
 - Install it, Learn how to use it, work out the pserver string, bang
   your head against CVS_RSH, eventually get it right.
 - For many users, discover for the first time that a firewall blocks
   port 2401, and you've wasted your time.
 - Wait n hours for 34M of Cocoon to download
 - find the xdoc you want to edit, build docs, wait, rinse, repeat
 - Search the web for "how to create a patch". Finally figure out 'cvs
   diff -u'.
 - Create a bugzilla account, create a doc enhancement request.

And that's your afternoon, if not your whole day, down the drain.

Moving to Forrest will make the edit turnaround cycle faster, at the
expense of an extra 10mb download.

So I agree with Diana about moving all docs to the Wiki.  It seems the
best long-term solution, avoiding all the problems that a dual wiki/xdoc
system would cause.


View raw message