Le Jeudi, 3 avr 2003, � 16:33 Europe/Zurich, Diana Shannon a �crit :
<lots-of-cool-stuff-snipped/>
...- 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.
-Bertrand
