cocoon-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Bertrand Delacretaz <>
Subject Re: xdocs vs. wiki docs (was: ...scrap the existing docs and start over?)
Date Fri, 04 Apr 2003 13:33:55 GMT
Le Vendredi, 4 avr 2003, à 13:40 Europe/Zurich, Diana Shannon a écrit :

> 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 
> of advocates like you. :-)

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

>> 1) There must be a way for users to know if a given version of a wiki 
>> doc has been reviewed/validated by committers, and by whom, so they 
>> can estimate the reliability of the document.
>> (I have ideas for this based on status files stored in CVS and 
>> dynamically read by a JSPWiki plugin from viewcvs, but let's not talk 
>> about tools ;-)
> Ok, let's try. However, this might be hard to do consistently, 
> especially with docs that relate to a particular configuration. Plus, 
> what if a user introduces something incorrect after it's been 
> validated? I know they could check diffs against a validation date, 
> but, that starts to get complicated.

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

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

Which could be translated to a small status table in the wiki page 
(after being pulled from CVS by JSPWiki over the viewcvs interface), in 
a different color if the file date is not what is in the status file 
anymore. "joe" is the committer who validated, "2.1" is the version 
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 
hard to maintain.
Maybe using a java properties file for the status file would make the 
plugin implementation easier and more flexible.

In this way committers could safely validate wiki content, and the 
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 
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 
>> 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 
> "approved" wiki pages for such releases, for example, without sandbox 
> pages, etc.. I was hoping this could happen with wiki -> xdocs (via 
> Forrest) with a linkmap that controlled which links expanded. Haven't 
> had time to experiment though.

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



View raw message