hy, everyone
It's time to round up i think. I have taken all the
emails from today and some from yesterday dealing with
this theme and extracted all information therein.
The following summary therefore contains snippets of
many people. I did some editing though to get things
into one document. Hopefully i didn't miss too much.
But you are invited to complete this roundup, if you
feel there is something missing.
The next steps should be : "clearification, decision"
happy reading
hussayn
--------------------------------------------
Proposal for the "Newbies Competence Center"
--------------------------------------------
I. The problem statement
========================
"Users can not get quickly started with Cocoon"
probable Causes:
1. The existing Cocoon documentation is poorly written
2. The existing Cocoon documentation is poorly structured
3. There are gaps in the existing Cocoon documentation
4. Some of the existing Cocoon documentation is located
in more than one site
5. ...(other issues related to installation/file size etc etc)
I. The goal of the "Newbies Competence Center"
==============================================
There is need to create documentation for people, who
are new to cocoon and want to try their first steps
in this technology. Some thoughts have been written
down in the cocoon-users mailing list.
The goal of this effort is to create a well defined, self
contained source of reliable information for Cocoon newbies,
along the lines of
"how to setup Cocoon in 15 minutes" and
"HOWTO setup your intranet with XML in 1 day".
The effort shall keep as tight as possible with the
already existing cocoon infrastructure and shall be
coordinated with the ongoing efforts on the cocoon core
documentation.
II. The requirements
====================
general remark:
There are severe doubts in creating a new documentation platform,
namely a new wiki site or a new documentation portal or whatever
disperses from the existing infrastructure. On the other hand the
existing infrastructure needs additional work in order to fit for
the requirements mentioned in the following list.
The most important requirements are:
2.1 MUST allow users to comment/improve the docs online to make
it as easy as possible
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.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.
2.4 MUST allow all docs to be searchable simultaneously, to prevent
users from having to search in X different places for info.
2.5 SHOULD if ever possible be integrated with existing Cocoon
community tools (documentation pages, cocoon wiki) to avoid
fragmentation of skills and resources
2.6 MUST provide constant "editors effort" to keep the documentation
set correlated, cleanly structured and up to date.
III. Additional thoughts
========================
o have a look at http://wiki.cocoondev.org/, you'll see a very
prominent link to a currently unexisting Main page for this
'NewbiesGuide'. Could be populated instantly.
o It was discussed, if the newbies documentation effort shall take
place within the cocoon core documentation team or coordinated
with that team and deveoped in parallel.
o There was an idea to redesign the cocoon documentation entry page
and provide chapters like:
1) First steps
2) User's Manual
3) User's Reference
4) Architecture
5) Developer's Guide
This could basically be achieved by reorganising existing
documentation.
o The complete cocoon documentation including the
"Newbies Competence Center" should be self contained,
published by cocoon itself and included into the distribution,
or set up as a separate documentation set, which can
be downloaded and integrated into cocoon webapp for online publishing.
o We need to be crystal clear and display on each page exactly
- who the target audience is
- what we assume of them in terms of background, knowledge and skills
We possibly can add pointers to XSLT, basics of XML and give them
some tips as to get up to speed ASAP.
o Another more visionary idea was:
What about having
- the cocoon documentation set for distribution
. manual pages
. possibly pdf for printout version
- the cocoon online site
including online access to the docs (multiple versions
of course, difference viewer as option)
- the cocoon documentation playground (wikipages)
- access to other related sites, bookstores,
this mailing list, commercial project enabler, ...
All of this tied together by the sunshine portal, or
jetspeed, or whatever....
Give it a newbies view, an experts view, a developers view,
a personal view....
o It is appreciated to use the existing wiki, mailing lists, CVS and
the existing web site, the idea being that the community can
concentrate on these three "tools" and not have a different tool
for each goal.
o Introduce something driven by "metadata", maybe simply adding
some name-value pairs at the end of the wiki text, e.g:
- TARGET-AUDIENCE: beginners
- REVIEWED-BY: [EMAIL PROTECTED], Tuesday January 28th, 2003
- COCOON-RELEASES: 2.0.1, 2.0.4
Which might be enough by itself by the way, but if this could
translate to cool-looking icons or different page backgrounds on
the wiki it would be very nice, and maybe not that hard to hack.
JSPWiki supports plugins, so maybe there is an easy way.
o How about adding a tab structure/frameset that toggles between
Wiki editing of the page and a metadata view. Using
Dublin Core's core elements, it makes it easy to create a
flexible form. The form consist of a toolbar containing a save
button and three dropdowns for the 3 DC categories
(Content, Intellectual Property, Instantiation).
The *.dcxml file is used to populate the form if it exists.
If new or adding an element, the user selects from the dropdown and
JavaScript writes a new row containing that metadata item.
Save puts it in the central location.
o lets have a wiki for people to add/suggest etc BUT
we need to take from it the most polished and relevant material
and make it into a formal and well laid-out website.
--
Dr. Hussayn Dabbous
SAXESS Software Design GmbH
Neuenhöfer Allee 125
50935 Köln
Telefon: +49-221-56011-0
Fax: +49-221-56011-20
E-Mail: [EMAIL PROTECTED]
---------------------------------------------------------------------
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]>
