Mailing-List: contact cocoon-docs-help@xml.apache.org; run by ezmlm
Precedence: bulk
Reply-To: cocoon-docs@xml.apache.org
Date: Fri, 4 Apr 2003 15:33:55 +0200
Subject: Re: xdocs vs. wiki docs  (was: ...scrap the existing docs and start
 over?)
Content-Type: text/plain; charset=ISO-8859-1; format=flowed
Mime-Version: 1.0 (Apple Message framework v551)
From: Bertrand Delacretaz <bdelacretaz@codeconsult.ch>
To: cocoon-docs@xml.apache.org
Content-Transfer-Encoding: quoted-printable
In-Reply-To: <31690AB7-6692-11D7-BAA4-0030653FE818@apache.org>
Message-Id: <14D42994-66A2-11D7-BF6E-000393CFE402@codeconsult.ch>

Le Vendredi, 4 avr 2003, =E0 13:40 Europe/Zurich, Diana Shannon a =E9crit =
:

> On Friday, April 4, 2003, at 02:20  AM, Bertrand Delacretaz wrote:
>
>> Although I've been and still am a strong advocate for wikis,
>
> I appreciate that, especially now. I consider myself a convert because=20=

> of advocates like you. :-)

Thanks!
The relationship between the Cocoon project and wikis might deserve a=20
book at some point ;-)


>> 1) There must be a way for users to know if a given version of a wiki=20=

>> doc has been reviewed/validated by committers, and by whom, so they=20=

>> can estimate the reliability of the document.
>> (I have ideas for this based on status files stored in CVS and=20
>> dynamically read by a JSPWiki plugin from viewcvs, but let's not talk=20=

>> about tools ;-)
>
> Ok, let's try. However, this might be hard to do consistently,=20
> especially with docs that relate to a particular configuration. Plus,=20=

> what if a user introduces something incorrect after it's been=20
> validated? I know they could check diffs against a validation date,=20
> but, that starts to get complicated.

It might not be that hard if the wiki page revision has a unique ID=20
(maybe simply the file time), then we could have a status file in CVS=20
like

   SomeFunnyWikiPage 2002-02-14 12:04:06 user:joe version:2.1=20
comments:intro needs some work, but otherwise ok

Which could be translated to a small status table in the wiki page=20
(after being pulled from CVS by JSPWiki over the viewcvs interface), in=20=

a different color if the file date is not what is in the status file=20
anymore. "joe" is the committer who validated, "2.1" is the version=20
against which this page was validated and the rest are comments.

This needs a JSPplugin to produce the status table but IMHO is not too=20=

hard to maintain.
Maybe using a java properties file for the status file would make the=20
plugin implementation easier and more flexible.

In this way committers could safely validate wiki content, and the=20
validations would be marked as stale if the pages are edited later on.
We don't need to go too far in this right now, I think there is a way=20
if we want to implement this but it is not the highest priority.

>
>> 2) There must be a way to archive the wiki docs when a release is=20
>> done so people using older releases can get docs that are in sync.
>> (possible with a static archive of the wiki HTML pages)
>
> Good point. I also think we need a way to generate a list of=20
> "approved" wiki pages for such releases, for example, without sandbox=20=

> pages, etc.. I was hoping this could happen with wiki -> xdocs (via=20
> Forrest) with a linkmap that controlled which links expanded. Haven't=20=

> had time to experiment though.

With the above mechanism, approved pages would be easily identifed.

<snip-agreed/>

-Bertrand=