cocoon-docs mailing list archives

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


> ...- separate out all docs relating to project administration, 
> licensing, etc. Keep a single instance of these somewhere. Maintain 
> these in xdocs. Refine/edit/refactor as approach

Let me reformulate to make sure we're in sync:
Keep the xdocs to the bare minimum: project info, sitemap and 
components reference, that's it?
All the rest (tutorial, examples, how-tos) is found on the "other doc 
system" mentioned below.

> - Refactor our reference docs to be produced by some kind of 
> auto-generation mechanism...

ok - I think we had a nice concept here.
(and the Chaperon parser could certainly help a lot for this but let's 
not talk about tools ;-)

> - Leave all the rest -- How-Tos, FAQs, Tutorials, Concepts -- to a 
> more open content system (via wiki/PHP-notes-like/simple CMS, > etc.)....

ok, I see your point with allowing users to contribute directly.

What we have today to implement this is the existing wiki - we don't 
want three different doc mechanisms, do we?

Although I've been and still am a strong advocate for wikis, I see 
three problems with this solution:

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

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)

3) Giving more importance to the wiki might put more strain on the wiki 
administrator who might have more work fighting with trolls or 
sabotage. Steven, what do you think?

If we can solve these issues I'm +1 on this concept: minimal xdocs, the 
rest on the wiki.


View raw message