Thanks for aggregating the recent discussions, it's a good step forward.
From my viewpoint of trying to use the existing "community tools", here are my thoughts on how the requirements could be implemented.
SAXESS - Hussayn Dabbous wrote:
>. . .
The most important requirements are:
2.1 MUST allow users to comment/improve the docs online to make
it as easy as possible
Comments from existing Cocoon website docs could also be implemented by add a link to a "wiki comments" page at the end of each doc.
2.2 MUST clearly identify these docs as being "for beginners" and
"reviewed by an editor of the Cocoon team" to prevent beginners
from getting lost in obsolete/unreliable docs. This could be
achieved by labeling the pages, using different layouts, colors,
etc.
2.2.a) We have good document plans for How-Tos etc. (see the IMHO excellent http://xml.apache.org/cocoon/howto/howto-author-howto.html for example).
Following such plans, even for wiki documents, goes a long way towards implementing this requirement.
2.2.b) Using the plugin mechanism of JSPWiki (see http://www.ecyrd.com/JSPWiki/Wiki.jsp?page=JSPWikiPlugins) it should be fairly easy to write plugins that generate nice icons or color bars out of WikiText like
[DocumentGroupPlugin group='tutorials']
[IntendedAudiencePlugin role='beginner']
[DocumentStatusPlugin
status='reviewed'
who='[EMAIL PROTECTED]'
when='Tuesday January 25th'
]
So that beginners can tell if a given page is meant for them or not.
I'm open to help implementing this, once I'm done with http://www.codeconsult.ch/blogs/bertrand-archives/000018.html.
2.3 SHOULD make these docs and their comments searchable, separately
from the technical and/or unchecked existing docs to prevent
beginners from being overwhelmed with irrelevant search results.
DocumentGroupPlugin group='tutorials'
in front of all queries when user wants to search tutorials only, for example.
2.4 MUST allow all docs to be searchable simultaneously, to prevent
users from having to search in X different places for info.
Ok on the current wiki
2.5 SHOULD if ever possible be integrated with existing Cocoon
community tools (documentation pages, cocoon wiki) to avoid
fragmentation of skills and resources
Ok with the current wiki
2.6 MUST provide constant "editors effort" to keep the documentation
set correlated, cleanly structured and up to date.
Creating reliable links is so easy on the wiki, it's no problem creating X different "table of contents" pages targeted to different audiences. This will help for this requirement too I think.
>. . .
So I think you see my point: these requirements *can* be implemented using the existing wiki at http://wiki.cocoondev.org/, and as I said yesterday this (compared to setting up something new) has the huuuuuuuuuuuge advantage of concentrating the community forces instead of dispersing them.
Again, you're very welcome to lead this documentation effort - please move the discussion to the cocoon-docs list if/once you make a decision about how to go on. I think Derek expressed his intention to help on this too.
Hopefully I'm being convincing - we need you guys aboard the boat, not sailing along in the dinghy ;-)
--
Bertrand Delacretaz (codeconsult.ch, jfor.org)
buzzwords: XML, java, XSLT, Cocoon, FOP, mentoring/teaching/coding.
blogspace http://www.codeconsult.ch/bertrand
---------------------------------------------------------------------
Please check that your question has not already been answered in the
FAQ before posting. <http://xml.apache.org/cocoon/faq/index.html>
To unsubscribe, e-mail: <[EMAIL PROTECTED]>
For additional commands, e-mail: <[EMAIL PROTECTED]>
