cocoon-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Tony Collen <tcol...@neuagency.com>
Subject Re: proposal: "The Newbies Competence Center"
Date Mon, 27 Jan 2003 18:40:20 GMT
CC:ing this to cocoon-docs because that's where it should go :)


On Mon, 27 Jan 2003, SAXESS - Hussayn Dabbous wrote:

> 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: someNiceFolk@apache.org, 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:  dabbous@saxess.com
>
>
> ---------------------------------------------------------------------
> 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