cocoon-users mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Bertrand Delacretaz <bdelacre...@codeconsult.ch>
Subject Re: proposal: "The Newbies Competence Center"
Date Tue, 28 Jan 2003 07:11:48 GMT
Hi Hussayn,

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

Ok on the existing wiki.

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.

Right now, only text labeling (using page titles etc.) can be done in 
the existing wiki, but

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='someNiceFolk@apache.org'
       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.

I'm not sure if searching *separately* is possible on the current wiki, 
but I didn't study its search features in detail. Ideally, we'd build on 
the above mechanism and create a search form that adds

   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.

Bugzilla and the cocoon-docs mailing list are here to help coordinating 
this effort. This is about people willing to do it, we have plenty 
enough tools to help here.

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:     <cocoon-users-unsubscribe@xml.apache.org>
For additional commands, e-mail:   <cocoon-users-help@xml.apache.org>


Mime
View raw message