You are viewing a plain text version of this content. The canonical link for it is here.
Posted to users@cocoon.apache.org by SAXESS - Hussayn Dabbous <da...@saxess.com> on 2003/01/27 19:40:04 UTC

proposal: "The Newbies Competence Center"

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


Re: proposal: "The Newbies Competence Center"

Posted by Bertrand Delacretaz <bd...@codeconsult.ch>.
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:     <co...@xml.apache.org>
For additional commands, e-mail:   <co...@xml.apache.org>


crosspost warning (was Re: proposal: "The Newbies Competence Center")

Posted by Bertrand Delacretaz <bd...@codeconsult.ch>.
Tony Collen wrote:
 >> CC:ing this to cocoon-docs because that's where it should go :)

You're right but the matter is still being discussed on cocoon-users,
and splitting the discussion might make it confusing.

I think it's better to continue the discussion on cocoon-users for now,
and move it cleanly here later on, but not have discussions in both places.

-Bertrand


crosspost warning (was Re: proposal: "The Newbies Competence Center")

Posted by Bertrand Delacretaz <bd...@codeconsult.ch>.
Tony Collen wrote:
 >> CC:ing this to cocoon-docs because that's where it should go :)

You're right but the matter is still being discussed on cocoon-users, 
and splitting the discussion might make it confusing.

I think it's better to continue the discussion on cocoon-users for now, 
and move it cleanly here later on, but not have discussions in both places.

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


Re: proposal: "The Newbies Competence Center"

Posted by Tony Collen <tc...@neuagency.com>.
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:     <co...@xml.apache.org>
> For additional commands, e-mail:   <co...@xml.apache.org>
>
>


Re: proposal: "The Newbies Competence Center"

Posted by Miles Elam <mi...@pcextremist.com>.
SAXESS - Hussayn Dabbous wrote:

> thank you for the very deep insight to several points here;
> i take this all very serious and will keep it in mind. especially
> because i consider my self beeing in the middle of step 3 (see below)
> now and still have lots to learn about cocoon. 


I'm still considering myself a beginner, so no conflict here.

> the proposal is not a proposal for a beginners tutorial. It is a
> proposal for a beginners documentation set, that should allow a newbie
> to start digging into cocoon up to step 3 (i assume) of your
> list...


I wonder, how much would be made clearer by keeping the introductory 
text on Cocoon (the somewhat philosophical overview) much the same and 
having a skeleton Cocoon installation?

For example, a sitemap with a bare minimum of components and just one 
pipeline and two matchers.  See my example at the bottom.

> Concerning the significance of avalon in XSP programming: i simply
> never touched XSP in cocoon-2 until today (although i am quite
> familiar with the concepts as i learned from cocoon-1 about two years 
> ago, but it changed alot...). Hopefully XSP will be my next step
> towards mastering cocoon-2. I thought from the ongoing discussion,
> that the underlaying technology wouldn't be soo evident as you state.
> as i said before i take you very serious and once i get to the
> point i will remember your very valuable insight to the theme. 


In Cocoon 1, I could see that.  In Cocoon 2, I think you would be 
hard-pressed to avoid XSP for longer than a week if you were seriously 
trying to solve a problem by using Cocoon.


* Beginner sitemap example *

Is this the type of thing that people are talking about?  I skipped most 
of the components.  Also, I completely ommitted actions, views, and 
selectors.  What other things would you want display to the absolute 
beginner?  The following sitemap expects the following extra files:

  index.html
  dynamic1.xsp
  dynamic2.xsp
  request2html.xsl
  xspoutput2html.xsl

where the XSP files would have a simple example like "hello world" 
and/or "The current time is..." and the index.html file is just a page 
of links to the other resources with a brief writeup.

- Miles



<?xml version="1.0" encoding="UTF-8"?>
<map:sitemap xmlns:map="http://apache.org/cocoon/sitemap/1.0">

  <!-- =========================== Components 
================================ -->

  <!-- This is where you define the components you want to use -->
  <!-- You define the actual working pipelines at the bottom of the 
sitemap -->

  <map:components>

      <map:generators default="file">
          <map:generator name="file" label="content,data" 
logger="sitemap.generator.file" pool-grow="4" pool-max="32" pool-min="8" 
src="org.apache.cocoon.generation.FileGenerator"/>
          <map:generator name="serverpages" label="content,data" 
logger="sitemap.generator.serverpages" pool-grow="2" pool-max="32" 
pool-min="4" src="org.apache.cocoon.generation.ServerPagesGenerator"/>
      </map:generators>

      <map:transformers default="xslt">
          <map:transformer name="xslt" 
logger="sitemap.transformer.xsltc" pool-grow="2" pool-max="32" 
pool-min="8" src="org.apache.cocoon.transformation.TraxTransformer">
              <use-request-parameters>false</use-request-parameters>
              
<use-browser-capabilities-db>false</use-browser-capabilities-db>
              
<transformer-factory>org.apache.xalan.xsltc.trax.TransformerFactoryImpl</transformer-factory>
          </map:transformer>
      </map:tranformers>

      <map:readers default="resource">
          <map:reader name="resource" logger="sitemap.reader.resource" 
pool-max="32" src="org.apache.cocoon.reading.ResourceReader"/>
      </map:readers>

      <map:serializers default="xml">
          <map:serializer name="xml" logger="sitemap.serializer.xml" 
mime-type="text/xml" src="org.apache.cocoon.serialization.XMLSerializer"/>
          <map:serializer name="html" logger="sitemap.serializer.html" 
mime-type="text/html" pool-grow="4" pool-max="32" pool-min="4" 
src="org.apache.cocoon.serialization.HTMLSerializer">
              <buffer-size>1024</buffer-size>
          </map:serializer>
      </map:serializers>

      <map:matchers default="wildcard">
          <map:matcher name="wildcard" logger="sitemap.matcher.wildcard" 
src="org.apache.cocoon.matching.WildcardURIMatcher"/>
      </map:matchers>

      <map:pipes default="caching">
          <map:pipe name="caching" 
src="org.apache.cocoon.components.pipeline.impl.CachingProcessingPipeline"/>
      </map:pipes>

  </map:components>

  <!-- =========================== Pipelines 
================================ -->
  <map:pipelines>

    <map:pipeline>

        <!-- The default page.  Note: Unless you explicitly declare a 
matcher for "index.html",
               you can only access it as "http://localhost:8080/" and 
not "http://localhost:8080/index.html" -->
        <map:match pattern="">
          <map:read src="index.html"/>
        </map:match>

        <!-- Returns the browser request information as XML -->
        <map:match pattern="request.xml">
            <map:generate type="request"/>
            <map:serialize type="xml"/>
        </map:match>

        <!-- Uses the previous matcher to generate an HTML version of 
the browser request -->
        <map:match pattern="request.html">
            <map:generate src="cocoon:/request.xml"/>
            <map:transform src="request2html.xsl"/>
            <map:serialize type="html"/>
        </map:match>

        <!-- Read in the content from the referenced XSP file -->
        <map:match pattern="dynamic*.xml">
            <map:generate type="serverpages" src="dynamic{1}.xsp"/>
            <map:serialize type="xml"/>
        </map:match>

        <!-- Uses the previous matcher to generate an HTML version of 
the XSP output -->
        <map:match pattern="*.html">
            <map:generate src="cocoon:/{1}.xml"/>
            <map:transform src="xspoutput2html.xsl"/>
            <map:serialize type="html"/>
        </map:match>

    </map:pipeline>

  </map:pipelines>
</map:sitemap>


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


Re: proposal: "The Newbies Competence Center"

Posted by SAXESS - Hussayn Dabbous <da...@saxess.com>.
Hy Miles;

thank you for the very deep insight to several points here;
i take this all very serious and will keep it in mind. especially
because i consider my self beeing in the middle of step 3 (see below)
now and still have lots to learn about cocoon.

just let me put one thing correct:

the proposal is not a proposal for a beginners tutorial. It is a
proposal for a beginners documentation set, that should allow a newbie
to start digging into cocoon up to step 3 (i assume) of your
list...

In this sense a tutorial might be only one peace of the whole set...

Concerning the significance of avalon in XSP programming: i simply
never touched XSP in cocoon-2 until today (although i am quite
familiar with the concepts as i learned from cocoon-1 about two years 
ago, but it changed alot...). Hopefully XSP will be my next step
towards mastering cocoon-2. I thought from the ongoing discussion,
that the underlaying technology wouldn't be soo evident as you state.
as i said before i take you very serious and once i get to the
point i will remember your very valuable insight to the theme.

thanks again,
regards, hussayn



Miles Elam wrote:
> SAXESS - Hussayn Dabbous wrote:
> 
>> * currently the docs do not really separate between
>>   cocoon-users and cocoon-developers and cocoon doesn't
>>   imply an obvious separation. 
> 
> 
> 
> On the contrary, on the homepage, there is a User Guide and a Dev 
> Guide.  I don't think that there lacks an obvious separation, but rather 
> an arbitrary separation.
> 
>> * the documentation seems to be more developer centric, less
>>   user centric. 
> 
> 
> 
> Think of Cocoon's target audience.  The greenest newbie is still 
> expected to be a web developer.  My aunt who's not in web development or 
> publishing couldn't care less about Cocoon.  The documentation *should* 
> be developer-centric.  A separation could be "Cocoon introduction for 
> developers" and "advanced Cocoon hacking for developers," but still, 
> this isn't technology for Joe Sixpack walking in off the street.  If all 
> someone wants is to publish a few HTML pages, even Microsoft's personal 
> web server would do the trick; Cocoon is overkill.  If someone off the 
> street wants to make an image slideshow/gallery, they shouldn't be 
> looking at Cocoon; They should be looking at a project built *on top of* 
> Cocoon.  The "Cocoon"part of it should be transparent to them: just 
> upload images and view in the web browser.
> 
> On the other hand, Cocoon docs should definitely be geared toward 
> someone wanting to *write* an image slideshow/gallery engine.
> 
>> * especially the newbies often get into trouble, because
>>   they feel, they have to learn the concepts in depths before
>>   they can get something out of cocoon. 
> 
> 
> 
> You have to learn what a sitemap is, what its purpose is, and how to use 
> it and the enclosed pipelines.  That's a must just as you must learn 
> Java and the basic tenets of OOP before you can get anything out of 
> servlets and JSP.  The only question is how this can be accomplished the 
> best.
> 
>> therefore we started this "newbies competence center" approach.
>> i personnaly whish, that eventually the whole cocoon documentation
>> will be better separated into developers issues and users issues,
>> where my definition (biased from the discussions) is a bit fuzzy:
>>
>> user:      *uses*    the given infrastructure as is
>> developer: *creates* his own add ons to given infrastructure 
> 
> 
> 
> When a user writes an XSP file, they are effectively creating a 
> generator -- create their own add on.  XSP files are definitely in the 
> category of "user introductory knowledge," however.
> 
> Would a more appropriate distinction be:
> 
> user:      uses or extends the given infrastructure as is
> developer: creates new infrastructure or alters existing infrastructure
> 
> Creating a generator for file format foo is the domain of the user.
> Editing or replacing AbstractGenerator or making fixes to the cache 
> store (shared resources) are the domain of the developer.
> 
>> I get troubles when it comes to xsp programming, which clearly
>> sits between the chairs. But even there i see a bunch of prepacked
>> ready to use logicsheets ready made  for the "users" and
>> the self made extra logicsheets from the developers...
>> maybe this is a little simplistic, but it may hold as a first
>> approach towards separating user concerns from developer concerns. 
> 
> 
> 
> I see XSP as the middle of the user bell-shaped curve.  What you are 
> talking about is not the documentation but the introductory tutorial.  
> The tutorial is important, but it is only a part of the overall 
> documentation.
> 
>> another argument was: the user does not deal with internals nor with
>> philosophy under the hood (like avalon framework, etc.) The developer
>> in contrary does.
> 
> 
> 
> Here we very much disagree.  In order to have your XSP file cache its 
> results, you need to reference Avalon components.  It's not an 
> all-or-nothing affair.  Almost everyone I've ever seen come to the list 
> has wondered about how fast Cocoon is.  If your XSPs aren't able to 
> cache, the answer is "not impressively fast."  There are only a few 
> Avalon interfaces/implementations you would ever need to know about or 
> use when you're starting out.  SourceValidity comes to mind...but it 
> needs to be documented better.
> 
>> all of this is not so easy and should be separated out more clearly
>> in the next steps. I am pretty shure, if we keep with KISS, we should
>> come out at least with a usable beginners doc though ;-) 
> 
> 
> 
> The pattern I see (the one I saw in myself) was:
> 1) First learning what makes Cocoon different and the general concept of 
> a sitemap.
> 2) Then the concept of a pipeline 
> (generators-to-tranformers-to-serializers).
> 3) Then seeing what components are available ("Ooh!  I can create a 
> directory listing as XML and use and include transformer to drop them in 
> place!  Neat-o!")
> 4) Then bumping into the wall of "I need to do X but I don't see a 
> ready-made component yet."
> 5a) Learning XSP to make simple items.
> 5b) Learning Actions to manipulate simple items.
> 6) Writing a component by extending an existing one.
> 7) Writing a component from scratch.
> 8) Hacking the Cocoon core.
> 
> I'm at about level 6 now.  (Is that a 1d8 or 2d4? :-))
> 
> Your tutorial, if it only handles the first three, would be a great 
> primer, but it has no bearing on the individual.  People will do 
> whatever is necessary to get their job done.  The first couple of steps 
> could be skipped and handled more easily by using JSP, PHP, etc. by 
> themselves.  A directory listing?  Apache's been doing that since its 
> introduction.  Cocoon is taking it to the next level.  Unfortunately, 
> "the next level" usually implies complexity.
> 
> The tutorial can only be the introduction to more knowledge.  It can't 
> ever serve the purpose of "this is all you need to get useful work 
> done."  That's like saying "I'll give a snippet of how while-loops and 
> declaring variables work so that you can write C code."  There 
> definitely should be a hello world demonstration, but don't be fooled.  
> A hello world example will enable you to edit sitemaps, see how it all 
> fits together, and write more apps with the complexity of hello world 
> (ie. not very useful apps).  It will teach 1 and 2 and let the user know 
> that 3 is on the horizon.  In the end, anyone who spends any amount of 
> time with Cocoon will go through all the steps (except maybe 7 and 8 -- 
> but I could be wrong).  This is because no real-world app is the same 
> complexity level as Hello World.
> 
> Cocoon: Making the impossible possible, the unmanageable manageable, and 
> -- when you are starting out -- the simple one-liners from Perl into 
> several days of research.
> 
> If all you need is the Perl one-liner, Cocoon will probably frustrate 
> you and leave you bitter.  If you're finding that the Perl one-liner 
> just won't cut it because you have hundreds of "one-liners" bouncing off 
> each other, then it's time to look at Cocoon.  (Ugh...  I feel like I 
> just transferred to marketing and sales.)
> 
> - Miles
> 
> 
> 
> ---------------------------------------------------------------------
> 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:     <co...@xml.apache.org>
> For additional commands, e-mail:   <co...@xml.apache.org>
> 

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


Re: proposal: "The Newbies Competence Center"

Posted by Miles Elam <mi...@pcextremist.com>.
SAXESS - Hussayn Dabbous wrote:

> * currently the docs do not really separate between
>   cocoon-users and cocoon-developers and cocoon doesn't
>   imply an obvious separation. 


On the contrary, on the homepage, there is a User Guide and a Dev 
Guide.  I don't think that there lacks an obvious separation, but rather 
an arbitrary separation.

> * the documentation seems to be more developer centric, less
>   user centric. 


Think of Cocoon's target audience.  The greenest newbie is still 
expected to be a web developer.  My aunt who's not in web development or 
publishing couldn't care less about Cocoon.  The documentation *should* 
be developer-centric.  A separation could be "Cocoon introduction for 
developers" and "advanced Cocoon hacking for developers," but still, 
this isn't technology for Joe Sixpack walking in off the street.  If all 
someone wants is to publish a few HTML pages, even Microsoft's personal 
web server would do the trick; Cocoon is overkill.  If someone off the 
street wants to make an image slideshow/gallery, they shouldn't be 
looking at Cocoon; They should be looking at a project built *on top of* 
Cocoon.  The "Cocoon"part of it should be transparent to them: just 
upload images and view in the web browser.

On the other hand, Cocoon docs should definitely be geared toward 
someone wanting to *write* an image slideshow/gallery engine.

> * especially the newbies often get into trouble, because
>   they feel, they have to learn the concepts in depths before
>   they can get something out of cocoon. 


You have to learn what a sitemap is, what its purpose is, and how to use 
it and the enclosed pipelines.  That's a must just as you must learn 
Java and the basic tenets of OOP before you can get anything out of 
servlets and JSP.  The only question is how this can be accomplished the 
best.

> therefore we started this "newbies competence center" approach.
> i personnaly whish, that eventually the whole cocoon documentation
> will be better separated into developers issues and users issues,
> where my definition (biased from the discussions) is a bit fuzzy:
>
> user:      *uses*    the given infrastructure as is
> developer: *creates* his own add ons to given infrastructure 


When a user writes an XSP file, they are effectively creating a 
generator -- create their own add on.  XSP files are definitely in the 
category of "user introductory knowledge," however.

Would a more appropriate distinction be:

user:      uses or extends the given infrastructure as is
developer: creates new infrastructure or alters existing infrastructure

Creating a generator for file format foo is the domain of the user.
Editing or replacing AbstractGenerator or making fixes to the cache 
store (shared resources) are the domain of the developer.

> I get troubles when it comes to xsp programming, which clearly
> sits between the chairs. But even there i see a bunch of prepacked
> ready to use logicsheets ready made  for the "users" and
> the self made extra logicsheets from the developers...
> maybe this is a little simplistic, but it may hold as a first
> approach towards separating user concerns from developer concerns. 


I see XSP as the middle of the user bell-shaped curve.  What you are 
talking about is not the documentation but the introductory tutorial.  
The tutorial is important, but it is only a part of the overall 
documentation.

> another argument was: the user does not deal with internals nor with
> philosophy under the hood (like avalon framework, etc.) The developer
> in contrary does.


Here we very much disagree.  In order to have your XSP file cache its 
results, you need to reference Avalon components.  It's not an 
all-or-nothing affair.  Almost everyone I've ever seen come to the list 
has wondered about how fast Cocoon is.  If your XSPs aren't able to 
cache, the answer is "not impressively fast."  There are only a few 
Avalon interfaces/implementations you would ever need to know about or 
use when you're starting out.  SourceValidity comes to mind...but it 
needs to be documented better.

> all of this is not so easy and should be separated out more clearly
> in the next steps. I am pretty shure, if we keep with KISS, we should
> come out at least with a usable beginners doc though ;-) 


The pattern I see (the one I saw in myself) was:
1) First learning what makes Cocoon different and the general concept of 
a sitemap.
2) Then the concept of a pipeline 
(generators-to-tranformers-to-serializers).
3) Then seeing what components are available ("Ooh!  I can create a 
directory listing as XML and use and include transformer to drop them in 
place!  Neat-o!")
4) Then bumping into the wall of "I need to do X but I don't see a 
ready-made component yet."
5a) Learning XSP to make simple items.
5b) Learning Actions to manipulate simple items.
6) Writing a component by extending an existing one.
7) Writing a component from scratch.
8) Hacking the Cocoon core.

I'm at about level 6 now.  (Is that a 1d8 or 2d4? :-))

Your tutorial, if it only handles the first three, would be a great 
primer, but it has no bearing on the individual.  People will do 
whatever is necessary to get their job done.  The first couple of steps 
could be skipped and handled more easily by using JSP, PHP, etc. by 
themselves.  A directory listing?  Apache's been doing that since its 
introduction.  Cocoon is taking it to the next level.  Unfortunately, 
"the next level" usually implies complexity.

The tutorial can only be the introduction to more knowledge.  It can't 
ever serve the purpose of "this is all you need to get useful work 
done."  That's like saying "I'll give a snippet of how while-loops and 
declaring variables work so that you can write C code."  There 
definitely should be a hello world demonstration, but don't be fooled.  
A hello world example will enable you to edit sitemaps, see how it all 
fits together, and write more apps with the complexity of hello world 
(ie. not very useful apps).  It will teach 1 and 2 and let the user know 
that 3 is on the horizon.  In the end, anyone who spends any amount of 
time with Cocoon will go through all the steps (except maybe 7 and 8 -- 
but I could be wrong).  This is because no real-world app is the same 
complexity level as Hello World.

Cocoon: Making the impossible possible, the unmanageable manageable, and 
-- when you are starting out -- the simple one-liners from Perl into 
several days of research.

If all you need is the Perl one-liner, Cocoon will probably frustrate 
you and leave you bitter.  If you're finding that the Perl one-liner 
just won't cut it because you have hundreds of "one-liners" bouncing off 
each other, then it's time to look at Cocoon.  (Ugh...  I feel like I 
just transferred to marketing and sales.)

- Miles



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


Re: proposal: "The Newbies Competence Center"

Posted by Niclas Hedhman <ni...@hedhman.org>.
Better yet, Cocoon already defines 4 "production roles", and add to that the 
"Cocoon Developer" we get;

1. Content
2. Style
3. Logic
4. Management/Admin
5. Cocoon Developer

Note that some docs can always be linked from more than one section. Same 
thing for a new FAQ section, where there could be multiple "target-role" for 
each Q and the generated FAQ would compile according to your 
"role-entrypoint".

Niclas

On Tuesday 28 January 2003 06:05, Robert Simmons wrote:
> In my opinion cocoon needs to start architecting itself towards four types
> of cocoon consumers:
>
> Presentation Developer:
> This person uses editors to define style sheets for transforming data into
> presentation layers. This user should not be concerned with the extension
> mechanism of cocoon. In a real company, this user would be a graphic
> designer. Should this user need some special kind of transformation, they
> would ask the next a Content Developer.
>
> Administrator:
> This person is responsible for maintaining the health of the cocoon
> instance. This user would typically be a network engineer at a company.
> They should have functionality to track throughput and performance and get
> an idea of the kind of volume being handled by cocoon via some statistics
> pages.
>
> Content Developer:
> Data is the prime responsibility for the content developer. He builds data
> engines using custom generator classes, static XML and various other
> mechanisms of cocoon. This user is served by a programmer in a company. The
> developer Is concerned only with the interface to cocoon and not with any
> of the internals. He doesn't need to know why things work, he just needs to
> know that if he implements interface x and generates content via sax
> events, then cocoon magically spits out his XML.
>
> Cocoon Developer:
> This is a consumer that is concerned with altering the cocoon distribution.
> This person has varying levels of knowledge of the internals of cocoon and
> seeks to contribute to the general product via commits to CVS.
>
> -----------------------------------
>
> To accomplish this we need, IMHO, to implement a few things in cocoon. The
> suggestions are annotated with the target roles indicated below their
> title. it is for these target roles that we do the task.
>
> Document the API:
> For (Cocoon Developer, Content Developer)
> Developers of cocoon should go through the entire API and document it.
> Using a tool like Jalopy, all of the source code can be formatted to
> standards set in the jalopy options. For each entry that is not documented,
> a todo list can be generated and worked through to remove all of the todo
> tag entries. Cocoon can be used to parse the javadoc files and, using XSLT,
> extract all of the todo entries. This would give the consumers the ability
> to use the API more effectively.
>
> Abstract Out References to third party libraries:
> (Cocoon Developer)
> Anytime the Cocoon Developer needs to build a new custom extension to
> cocoon, he should have to only import the cocoon.jar file into his
> classpath to compile. All of these interfaces will then be documented in
> one API document set for easy consumption. This would be accomplished by
> identifying all entry points and facading them with interfaces. So the
> avalon request object would instead be org.apache.cocoon.api.Request. The
> user deals only with the interfaces and not with anything internal.
>
> Convert logging to use Log4j:
> (Administrator, Content Developer, Cocoon Developer)
> This would involve converting Logikit logging to Log4j logging mechanisms.
> Although pervasive throughout the code, the changes are mostly a bunch of
> search and replace activities. It can hardly be denied that Log4j has won
> the Java logging market. There are already a number of professional tools
> used for viewing Log4j output. Such tools as those used in consuming JMS
> logging events are used by network engineers all over to monitor health of
> the system. There is little point trying to fight the tide. Making Cocoon
> use Log4j would have the advantage of allowing these network admins to
> configure single Log4j property files for their whole platform.
>
> Build documentation specifically targeted at each user role:
> (all)
> This documentation should include getting started guides for all four types
> of users and varying levels of tutorials. For instance Presentation
> Developers might get a tutorial on XSL and XML. Content Developers would
> get current tutorials such as making your own generator and introduction to
> forms in XSL. In addition, other tutorials such as the sitemap tutorial
> would be common to all roles. This documentation should be sectioned
> appropriate to the roles.
>
> Create a distribution stripped of every example except a single XML-XSL
> transform welcome page for use as a starter point.
> (Content Developer)
>
> Change the Libs format:
> (Content Developer)
> The libs should all be packaged into one big jar containing each of the
> other library jars. This library would contain a classpath for each of the
> entries in the big jar file. This would hide internals from the cocoon
> developers.
>
> A new jar called cocoon-ext.jar.
> (Content Developer)
> This jar would contain only the needed classes for compiling extensions
> (such as generators) to cocoon. It would be for users to mount in their
> development IDEs instead of having to mount the entire cocoon-all.jar. In
> the
> distribution, a new directory called dev-libs would be created and this jar
> would be placed in there.
>
> All properties and xconf files that the user doesn't need to routinely edit
> would be packed into the cocoon-all.jar.
> (Content Developer)
> The code loading these files would be adapted so that if a user chooses to
> provide his own xconf files (at his own risk), he can do so. Perhaps the
> code looks for custom-cocoon.xconf  in the classpath and if it doesn't find
> it, then it loads the default one in the cocoon-all.jar.
>
> Finalize a Sitemap Schema:
> (Content Developer, Presentation Developer)
> Being able to validate against the schema would be a big help to these two
> roles.
>
> Comprehensive reference manual:
> (all)
> This would contain things such as a dictionary of common terms and a list
> of the generators and what each does. It would be brief reference material
> used to help the cocoon consumers. All properties for the cocoon.xconf
> files and various other files would be enumerated and so on.
>
>
>
>
> ----- Original Message -----
> From: "SAXESS - Hussayn Dabbous" <da...@saxess.com>
> To: <co...@xml.apache.org>
> Sent: Monday, January 27, 2003 8:52 PM
> Subject: Re: proposal: "The Newbies Competence Center"
>
> > From the ongoing discussion we (the users) stated, that :
> >
> > * currently the docs do not really separate between
> >    cocoon-users and cocoon-developers and cocoon doesn't
> >    imply an obvious separation.
> >
> > * the documentation seems to be more developer centric, less
> >    user centric.
> >
> > * especially the newbies often get into trouble, because
> >    they feel, they have to learn the concepts in depths before
> >    they can get someth8ing out of cocoon.
> >
> > therefore we started this "newbies competence center" approach.
> > i personnaly whish, that eventually the whole cocoon documentation
> > will be better separated into developers issues and users issues,
> > where my definition (biased from the discussions) is a bit fuzzy:
> >
> > user:      *uses*    the given infrastructure as is
> > developer: *creates* his own add ons to given infrastructure
> >
> > I get troubles when it comes to xsp programming, which clearly
> > sits between the chairs. But even there i see a bunch of prepacked
> > ready to use logicsheets ready made  for the "users" and
> > the self made extra logicsheets from the developers...
> > maybe this is a little simplistic, but it may hold as a first
> > approach towards separating user concerns from developer concerns.
> >
> > another argument was: the user does not deal with internals nor with
> > philosophy under the hood (like avalon framework, etc.) The developer
> > in contrary does. But even here there seem to be at least two kinds
> > of developers at work: those who do "simple" add ons (whatever
> > simple means) i name them "application programmers" (they won't
> > dive deep into avalon) and those who create complex additions to the
> > cocoon base, who may be labeled as system programmers.
> >
> > all of this is not so easy and should be separated out more clearly
> > in the next steps. I am pretty shure, if we keep with KISS, we should
> > come out at least with a usable beginners doc though ;-)
> >
> > regards, hussayn
> >
> > Tony Collen wrote:
> > > Remember, the docs are for the users, and unfortunately, the developers
> > > might have a different idea about how the information "should" be
> > > categorized.    Or maybe our problem is making the distinction between
> > > "users" and "developers" ...  I would guess that eventually, most users
> > > become developers, so then, it's just a matter of "beginning user" vs.
> > > "power user", and so on.
> >
> > --
> > 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:     <co...@xml.apache.org>
> > For additional commands, e-mail:   <co...@xml.apache.org>
>
> ---------------------------------------------------------------------
> 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:     <co...@xml.apache.org>
> For additional commands, e-mail:   <co...@xml.apache.org>


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


Re: proposal: "The Newbies Competence Center"

Posted by Robert Simmons <de...@arcor.de>.
In my opinion cocoon needs to start architecting itself towards four types of
cocoon consumers:

Presentation Developer:
This person uses editors to define style sheets for transforming data into
presentation layers. This user should not be concerned with the extension
mechanism of cocoon. In a real company, this user would be a graphic
designer. Should this user need some special kind of transformation, they
would ask the next a Content Developer.

Administrator:
This person is responsible for maintaining the health of the cocoon instance.
This user would typically be a network engineer at a company. They should
have functionality to track throughput and performance and get an idea of the
kind of volume being handled by cocoon via some statistics pages.

Content Developer:
Data is the prime responsibility for the content developer. He builds data
engines using custom generator classes, static XML and various other
mechanisms of cocoon. This user is served by a programmer in a company. The
developer Is concerned only with the interface to cocoon and not with any of
the internals. He doesn't need to know why things work, he just needs to know
that if he implements interface x and generates content via sax events, then
cocoon magically spits out his XML.

Cocoon Developer:
This is a consumer that is concerned with altering the cocoon distribution.
This person has varying levels of knowledge of the internals of cocoon and
seeks to contribute to the general product via commits to CVS.

-----------------------------------

To accomplish this we need, IMHO, to implement a few things in cocoon. The
suggestions are annotated with the target roles indicated below their title.
it is for these target roles that we do the task.

Document the API:
For (Cocoon Developer, Content Developer)
Developers of cocoon should go through the entire API and document it. Using
a tool like Jalopy, all of the source code can be formatted to standards set
in the jalopy options. For each entry that is not documented, a todo list can
be generated and worked through to remove all of the todo tag entries. Cocoon
can be used to parse the javadoc files and, using XSLT, extract all of the
todo entries. This would give the consumers the ability to use the API more
effectively.

Abstract Out References to third party libraries:
(Cocoon Developer)
Anytime the Cocoon Developer needs to build a new custom extension to cocoon,
he should have to only import the cocoon.jar file into his classpath to
compile. All of these interfaces will then be documented in one API document
set for easy consumption. This would be accomplished by identifying all entry
points and facading them with interfaces. So the avalon request object would
instead be org.apache.cocoon.api.Request. The user deals only with the
interfaces and not with anything internal.

Convert logging to use Log4j:
(Administrator, Content Developer, Cocoon Developer)
This would involve converting Logikit logging to Log4j logging mechanisms.
Although pervasive throughout the code, the changes are mostly a bunch of
search and replace activities. It can hardly be denied that Log4j has won the
Java logging market. There are already a number of professional tools used
for viewing Log4j output. Such tools as those used in consuming JMS logging
events are used by network engineers all over to monitor health of the
system. There is little point trying to fight the tide. Making Cocoon use
Log4j would have the advantage of allowing these network admins to configure
single Log4j property files for their whole platform.

Build documentation specifically targeted at each user role:
(all)
This documentation should include getting started guides for all four types
of users and varying levels of tutorials. For instance Presentation
Developers might get a tutorial on XSL and XML. Content Developers would get
current tutorials such as making your own generator and introduction to forms
in XSL. In addition, other tutorials such as the sitemap tutorial would be
common to all roles. This documentation should be sectioned appropriate to
the roles.

Create a distribution stripped of every example except a single XML-XSL
transform welcome page for use as a starter point.
(Content Developer)

Change the Libs format:
(Content Developer)
The libs should all be packaged into one big jar containing each of the other
library jars. This library would contain a classpath for each of the entries
in the big jar file. This would hide internals from the cocoon developers.

A new jar called cocoon-ext.jar.
(Content Developer)
This jar would contain only the needed classes for compiling extensions (such
as generators) to cocoon. It would be for users to mount in their development
IDEs instead of having to mount the entire cocoon-all.jar. In the
distribution, a new directory called dev-libs would be created and this jar
would be placed in there.

All properties and xconf files that the user doesn't need to routinely edit
would be packed into the cocoon-all.jar.
(Content Developer)
The code loading these files would be adapted so that if a user chooses to
provide his own xconf files (at his own risk), he can do so. Perhaps the code
looks for custom-cocoon.xconf  in the classpath and if it doesn't find it,
then it loads the default one in the cocoon-all.jar.

Finalize a Sitemap Schema:
(Content Developer, Presentation Developer)
Being able to validate against the schema would be a big help to these two
roles.

Comprehensive reference manual:
(all)
This would contain things such as a dictionary of common terms and a list of
the generators and what each does. It would be brief reference material used
to help the cocoon consumers. All properties for the cocoon.xconf files and
various other files would be enumerated and so on.




----- Original Message -----
From: "SAXESS - Hussayn Dabbous" <da...@saxess.com>
To: <co...@xml.apache.org>
Sent: Monday, January 27, 2003 8:52 PM
Subject: Re: proposal: "The Newbies Competence Center"


> From the ongoing discussion we (the users) stated, that :
>
> * currently the docs do not really separate between
>    cocoon-users and cocoon-developers and cocoon doesn't
>    imply an obvious separation.
>
> * the documentation seems to be more developer centric, less
>    user centric.
>
> * especially the newbies often get into trouble, because
>    they feel, they have to learn the concepts in depths before
>    they can get someth8ing out of cocoon.
>
> therefore we started this "newbies competence center" approach.
> i personnaly whish, that eventually the whole cocoon documentation
> will be better separated into developers issues and users issues,
> where my definition (biased from the discussions) is a bit fuzzy:
>
> user:      *uses*    the given infrastructure as is
> developer: *creates* his own add ons to given infrastructure
>
> I get troubles when it comes to xsp programming, which clearly
> sits between the chairs. But even there i see a bunch of prepacked
> ready to use logicsheets ready made  for the "users" and
> the self made extra logicsheets from the developers...
> maybe this is a little simplistic, but it may hold as a first
> approach towards separating user concerns from developer concerns.
>
> another argument was: the user does not deal with internals nor with
> philosophy under the hood (like avalon framework, etc.) The developer
> in contrary does. But even here there seem to be at least two kinds
> of developers at work: those who do "simple" add ons (whatever
> simple means) i name them "application programmers" (they won't
> dive deep into avalon) and those who create complex additions to the
> cocoon base, who may be labeled as system programmers.
>
> all of this is not so easy and should be separated out more clearly
> in the next steps. I am pretty shure, if we keep with KISS, we should
> come out at least with a usable beginners doc though ;-)
>
> regards, hussayn
>
> Tony Collen wrote:
> >
> > Remember, the docs are for the users, and unfortunately, the developers
> > might have a different idea about how the information "should" be
> > categorized.    Or maybe our problem is making the distinction between
> > "users" and "developers" ...  I would guess that eventually, most users
> > become developers, so then, it's just a matter of "beginning user" vs.
> > "power user", and so on.
> >
> --
> 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:     <co...@xml.apache.org>
> For additional commands, e-mail:   <co...@xml.apache.org>
>


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


Re: proposal: "The Newbies Competence Center"

Posted by Upayavira <uv...@upaya.co.uk>.
> user:      *uses*    the given infrastructure as is
> developer: *creates* his own add ons to given infrastructure
> 
> I get troubles when it comes to xsp programming, which clearly
> sits between the chairs. But even there i see a bunch of prepacked
> ready to use logicsheets ready made  for the "users" and the self made
> extra logicsheets from the developers... maybe this is a little
> simplistic, but it may hold as a first approach towards separating
> user concerns from developer concerns.

How about this as a distinction:

You switch from being a user to a developer when you consciously invoke a Java 
compiler.

XSP to my mind is still in the user space. You are using functionality provided to you 
by cocoon, even if that is programming functionality. But if you write your own 
generator, then you're moving into the developer space, because, depending upon 
exactly what you choose to do with your generator, you might start to need to know 
more about Cocoon internals, Avalon, etc.

Regards, Upayavira


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


Re: proposal: "The Newbies Competence Center"

Posted by Miles Elam <mi...@pcextremist.com>.
Tony Collen wrote:

>For instance, with a typical installation of Cocoon, we could define the
>following roles:
>
>	- Content Creator.  This person authors XML for the site to be
>transformed.  This role works when most of the content is static.
>However, if a lot of the data is being pulled out of a database, they
>would be in charge of something like data entry into the database, etc.
>

I've been seeing this role work out well in practice.  There is 
grumbling when they can't mark up their content significantly like they 
used to in Frontpage or Dreamweaver, but after seeing a demo, they 
usually acquiesce.

>	- Graphic/Web designer.  This person is in charge of the style of
>the site.  Not only do they come up with how the site looks through the
>design of the final HTML, but they also write the XSL to transform the
>content into the desired format.  Sometimes this person is also the
>content creator.
>

This role, however, falls apart quickly.  There are three roles here and 
it's rare that any one person satisfies all of the roles successfully.

1) The graphic designer:
     The artist/production manager who is a whiz with Photoshop/Paint 
Shop Pro/The GIMP.  They design the overall look and feel for the site.  
Anyone who has seen a good graphic artist can attest to the fact that 
not everyone can do the job.

2) The HTML/CSS web monkey (term of endearment -- not meant to offend):
     Can take the layout design from the graphic artist and turn it into 
clean and useable HTML/CSS markup.  Frontpage et al are useless in this 
regard.

3) The XSLT author:
     Transforms the internal XML document to the web monkey's HTML 
model.  This role is commonly found in the engineering department and is 
needed for the non-presentational transformations that occur quite often 
in Cocoon as well.

In my opinion, it is by far the greatest amount of work in site 
production in terms of getting off the ground.

>	- Administrator.  In charge of the servlet container, and
>modifying the main sitemap.  Monitors logs, and able to identify
>when a component would need to be cacheable, poolable, etc.  Sometimes
>this role can further be separated out into servlet container admin and
>sitemap admin.
>

Developers too often need to edit the sitemap for this.  The 
Administrator definitely deals with installing software packages (would 
be in charge of installing blocks for example) and maintaining the 
servlet container/EJB container.  But the sitemap is definitely drifting 
into the lead developer's domain with subsitemaps handled by subproject 
leads.  Could you imagine asking a sysadmin to switch the cinclude 
transformer to a non-caching variety on URL pattern X?  I can, however, 
see a lead developer editing the sitemap locally on a development box 
and asking the sysadmin to upload the changes.

>	- Programmer.  I think this is what we now call "developer" --
>this person is capable of developing custom components, e.g. Generators,
>XSPs, etc.  This person might also code the Flow layer logic.  But maybe
>not.
>

And this person would definitely need to have access to a sitemap for 
testing and deployment.  They can't work in a bubble.  New generators 
and XSPs go hand in hand with at least one new URL pattern in the sitemap.

>Ideally, all of these roles work together in order to get things done, but
>they only have to worry about their specific role.
>

I have come to believe this is a fairy tale.  No individual in a 
development group, in my opinion, can *ever* worry about just their 
role.  They can specialize on their role, but you can't make a rigid 
wall here.  Maybe as Cocoon (and more specifically, Cocoon's best 
practices) matures, this may get better.

What Cocoon has done is allow each role to define their contracts with 
which to work with each other.  The content authors always make 
documents according to a particular schema (although more likely, they 
are filling in a web form or using some standalone data entry client), 
and no matter how the layout or storage method changes, their work is 
safe.  Their schema is their contract.  The programmer puts the content 
away and retrieves in again.  They respect the content author's contract 
(usually they defined the contract) and can switch datastores, 
versioning, access points, etc. without disturbing the way the content 
authors work.  The presentation group takes the content made by the 
content authors and made available by the programmers (and/or site 
administrator) and is assured of their result because they know their 
inputs -- the contracts -- are defined.

This is not the same as ignorance of each others' roles in a working 
group.  This is simply allowing each to easily work in parallel without 
stepping on each others' toes.  The day that each group only worries 
about their role and no one else's is the day that communication stops 
and things start to suffer.  Cocoon allows these concerns to be 
separated so that while people can negotiate their contracts (to coin a 
phrase), there is no point to a content author getting into the details 
of a generator.  Their contract is fulfilled when they write their 
content.  It works because it's *harder* in Cocoon to find justification 
to step on someone else's work, but that doesn't mean, for example, that 
a programmer can't be interested in what the designer is making or help 
in design work.  It just means that the artistically gifted programmer 
starts working with a different contract in mind.

With JSPs, you only had self-control and discipline to maintain the 
contracts (assuming the contracts were adopted in the first place).  
Cocoon is simply codifying it: making the right thing easier to do than 
the wrong thing.

>Now that we have defined roles, its easy to classify the documentation we
>have now.  Obviously, the content creator doesn't have to worry about
>performance issues, so perhaps that info would go into the Administrator
>section.  Likewise for information about logging.  Conversely, people
>writing a custom generator obviously fall into the Programmer category,
>and they would probably know not to have to stumble into the
>"Administrator" section.
>

A content creator wouldn't have to know, but everyone else would.  
Profiling XSLT, efficient generators, DOM vs. SAX in your components, 
making your component cacheable, store settings.  These are all 
performance related but they aren't all the domain of the administrator.

>To sum up, Cocoon was developed with SoC in mind.  IMHO, the current
>documentation managed to comingle the concerns, so we ended up with 4 or 5
>different places that something could go.  If we mirror the SoC model in
>the documentation, I think we'll end up with some successful and useful
>docs.
>

I think this is a bad idea for the reasons stated above.

Since it's Super Bowl season here in the U.S., I'll use a (American) 
football analogy.  Before Cocoon, in the heady days of just JSP, ASP, 
and PHP, it was a pickup game at the park.  The role of quarterback is 
constantly changing who it applies to and everyone's scrambling in all 
different directions.  People generally enjoy themselves and are hostile 
to the idea that people should be assigned roles and stick with them.  
Then another group of people comes by that wants to join in the game.  
No one knows each other and there are a lot more fumbles and people are 
more likely to get hurt because they don't know the rules to the game.

Cocoon is getting closer to league play where people get on the team as 
a quarterback or as a center or as a wide receiver.  The have a 
particular role and they serve that role well, but they need to know 
what the other folks are doing.  They need to have flexibility and be 
able to adapt to the other roles when the need arises.

These are, of course, my opinion on the matter.

- Miles



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


Re: proposal: "The Newbies Competence Center"

Posted by SAXESS - Hussayn Dabbous <da...@saxess.com>.
Thinking about the concept of roles is really the best
conceptual input to the docs i heard so far.

Yes, i have the instant feeling, that your list of
roles is highly significant. That should be taken
into account when going into the newbies documentation ...

thanks alot for this contrib !!!!
regards, hussayn

Tony Collen wrote:
> On Mon, 27 Jan 2003, SAXESS - Hussayn Dabbous wrote:
> 
> 
>>therefore we started this "newbies competence center" approach.
>>i personnaly whish, that eventually the whole cocoon documentation
>>will be better separated into developers issues and users issues,
>>where my definition (biased from the discussions) is a bit fuzzy:
>>
>>user:      *uses*    the given infrastructure as is
>>developer: *creates* his own add ons to given infrastructure
> 
> 
> Hrmm... this gives me an idea, tell me if you follow along:
> 
> Cocoon was developed with SoC in mind.  You have the content separated
> from the style, and you have the logic of the site separated from the
> content.
> 
> So, instead of trying to define what a user is and what a developer is, we
> should define the different roles that a person would have when using or
> developing with Cocoon.
> 
> For instance, with a typical installation of Cocoon, we could define the
> following roles:
> 
> 	- Content Creator.  This person authors XML for the site to be
> transformed.  This role works when most of the content is static.
> However, if a lot of the data is being pulled out of a database, they
> would be in charge of something like data entry into the database, etc.
> 
> 	- Graphic/Web designer.  This person is in charge of the style of
> the site.  Not only do they come up with how the site looks through the
> design of the final HTML, but they also write the XSL to transform the
> content into the desired format.  Sometimes this person is also the
> content creator.
> 
> 	- Administrator.  In charge of the servlet container, and
> modifying the main sitemap.  Monitors logs, and able to identify
> when a component would need to be cacheable, poolable, etc.  Sometimes
> this role can further be separated out into servlet container admin and
> sitemap admin.
> 
> 	- Programmer.  I think this is what we now call "developer" --
> this person is capable of developing custom components, e.g. Generators,
> XSPs, etc.  This person might also code the Flow layer logic.  But maybe
> not.
> 
> Ideally, all of these roles work together in order to get things done, but
> they only have to worry about their specific role.
> 
> Now that we have defined roles, its easy to classify the documentation we
> have now.  Obviously, the content creator doesn't have to worry about
> performance issues, so perhaps that info would go into the Administrator
> section.  Likewise for information about logging.  Conversely, people
> writing a custom generator obviously fall into the Programmer category,
> and they would probably know not to have to stumble into the
> "Administrator" section.
> 
> To sum up, Cocoon was developed with SoC in mind.  IMHO, the current
> documentation managed to comingle the concerns, so we ended up with 4 or 5
> different places that something could go.  If we mirror the SoC model in
> the documentation, I think we'll end up with some successful and useful
> docs.
> 
> 
> 
> Regards,
> 
> Tony
> 
> --
> Cocoon: Internet Glue (A Cocoon Weblog)
> http://manero.org/weblog/
> 
> 
> 
> ---------------------------------------------------------------------
> 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:     <co...@xml.apache.org>
> For additional commands, e-mail:   <co...@xml.apache.org>
> 

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


Re: proposal: "The Newbies Competence Center"

Posted by Tony Collen <tc...@neuagency.com>.
On Mon, 27 Jan 2003, SAXESS - Hussayn Dabbous wrote:

> therefore we started this "newbies competence center" approach.
> i personnaly whish, that eventually the whole cocoon documentation
> will be better separated into developers issues and users issues,
> where my definition (biased from the discussions) is a bit fuzzy:
>
> user:      *uses*    the given infrastructure as is
> developer: *creates* his own add ons to given infrastructure

Hrmm... this gives me an idea, tell me if you follow along:

Cocoon was developed with SoC in mind.  You have the content separated
from the style, and you have the logic of the site separated from the
content.

So, instead of trying to define what a user is and what a developer is, we
should define the different roles that a person would have when using or
developing with Cocoon.

For instance, with a typical installation of Cocoon, we could define the
following roles:

	- Content Creator.  This person authors XML for the site to be
transformed.  This role works when most of the content is static.
However, if a lot of the data is being pulled out of a database, they
would be in charge of something like data entry into the database, etc.

	- Graphic/Web designer.  This person is in charge of the style of
the site.  Not only do they come up with how the site looks through the
design of the final HTML, but they also write the XSL to transform the
content into the desired format.  Sometimes this person is also the
content creator.

	- Administrator.  In charge of the servlet container, and
modifying the main sitemap.  Monitors logs, and able to identify
when a component would need to be cacheable, poolable, etc.  Sometimes
this role can further be separated out into servlet container admin and
sitemap admin.

	- Programmer.  I think this is what we now call "developer" --
this person is capable of developing custom components, e.g. Generators,
XSPs, etc.  This person might also code the Flow layer logic.  But maybe
not.

Ideally, all of these roles work together in order to get things done, but
they only have to worry about their specific role.

Now that we have defined roles, its easy to classify the documentation we
have now.  Obviously, the content creator doesn't have to worry about
performance issues, so perhaps that info would go into the Administrator
section.  Likewise for information about logging.  Conversely, people
writing a custom generator obviously fall into the Programmer category,
and they would probably know not to have to stumble into the
"Administrator" section.

To sum up, Cocoon was developed with SoC in mind.  IMHO, the current
documentation managed to comingle the concerns, so we ended up with 4 or 5
different places that something could go.  If we mirror the SoC model in
the documentation, I think we'll end up with some successful and useful
docs.



Regards,

Tony

--
Cocoon: Internet Glue (A Cocoon Weblog)
http://manero.org/weblog/



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


Re: proposal: "The Newbies Competence Center"

Posted by SAXESS - Hussayn Dabbous <da...@saxess.com>.
 From the ongoing discussion we (the users) stated, that :

* currently the docs do not really separate between
   cocoon-users and cocoon-developers and cocoon doesn't
   imply an obvious separation.

* the documentation seems to be more developer centric, less
   user centric.

* especially the newbies often get into trouble, because
   they feel, they have to learn the concepts in depths before
   they can get someth8ing out of cocoon.

therefore we started this "newbies competence center" approach.
i personnaly whish, that eventually the whole cocoon documentation
will be better separated into developers issues and users issues,
where my definition (biased from the discussions) is a bit fuzzy:

user:      *uses*    the given infrastructure as is
developer: *creates* his own add ons to given infrastructure

I get troubles when it comes to xsp programming, which clearly
sits between the chairs. But even there i see a bunch of prepacked
ready to use logicsheets ready made  for the "users" and
the self made extra logicsheets from the developers...
maybe this is a little simplistic, but it may hold as a first
approach towards separating user concerns from developer concerns.

another argument was: the user does not deal with internals nor with
philosophy under the hood (like avalon framework, etc.) The developer
in contrary does. But even here there seem to be at least two kinds
of developers at work: those who do "simple" add ons (whatever
simple means) i name them "application programmers" (they won't
dive deep into avalon) and those who create complex additions to the
cocoon base, who may be labeled as system programmers.

all of this is not so easy and should be separated out more clearly
in the next steps. I am pretty shure, if we keep with KISS, we should
come out at least with a usable beginners doc though ;-)

regards, hussayn

Tony Collen wrote:
> 
> Remember, the docs are for the users, and unfortunately, the developers
> might have a different idea about how the information "should" be
> categorized.    Or maybe our problem is making the distinction between
> "users" and "developers" ...  I would guess that eventually, most users
> become developers, so then, it's just a matter of "beginning user" vs.
> "power user", and so on.
> 
-- 
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:     <co...@xml.apache.org>
For additional commands, e-mail:   <co...@xml.apache.org>


Re: proposal: "The Newbies Competence Center"

Posted by Miles Elam <mi...@pcextremist.com>.
Tony Collen wrote:

>On Mon, 27 Jan 2003, SAXESS - Hussayn Dabbous wrote:
>
>  
>
>>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 is good. HOWEVER, occasionally the line between "user" and
>"developer" gets blurred, especially when a user realizes they need to
>develop a custom component.
>
>All too often, I've gone to the developer section looking for information
>that was actually in the user guide, and vice versa.
>
I totally agree.  In fact, this is an item that I took issue with in 
Lajos and Jeremy's book: which "Generators" section should I be looking 
in?  I also don't know that a quick reference and a manual must be 
distinct items.  For a printed book, this makes a lot of sense.  But the 
web is inherently a quick reference -- bouncing from relevant topic to 
relevant topic.  This is an area where I think the existing 
documentation (for some components) shines.  If you take a look at the 
Request XSP logicsheet 
(http://xml.apache.org/cocoon/userdocs/xsp/request.html), this is an 
example of what I mean.  If the page simply had quick, in-page links to 
description, usage, examples, and quick reference, you would be done.  A 
user looking up information says, "Hmmm, I know I want to use a 
serializer so I'll go to the serializer section."  From there, they can 
select if they want an example, an API lookup, etc.  Quick references 
exist because no one wants to haul around five hundred page books.  But 
if you are on the web, you already have access to a million page book.  
The same rules don't apply.

However, I think the above list has merit if you clearly define what 
"development" is.  I tend to think that *anyone* who installs Cocoon and 
edits something to be a developer rather than a user.  The users, in my 
mind, are the folks using the web browser.  There are, however, 
different classes of developer.  For example, if you write an XSP 
document, you've in essense written a generator.  No, they didn't call 
javac themselves, but it's only slightly different.  The difference 
mainly lies in its relative ease, not in the intent.  If you set up a 
pipeline in the sitemap, what are you if not a developer assembling 
components together?

On the other hand, making changes to the Flow engine, the cache store, 
the sitemap parser, etc. are definitely different from writing your own 
transformer.  The distinction in the documentation should be "here are 
things you can do for your own benefit that affect no one else" and 
"here are things that fundamentally affect the requirements for other 
components."

For example:

1) Architecture Overview/Primer/First Steps
  a) Why Cocoon exists
  b) Quick start installation
  c) Hello World (XSP document going through a simple transformer and 
serializing to HTML)
  d) Very brief introduction to sitemaps, generators, etc. by explaining 
Hello World

2) The Cocoon servlet
  a) Installation instructions
    i) Tomcat
    ii) Jetty
    iii) JBoss
    iv) etc.
  b) Web app layout
    i) Configuration locations (logkit.xconf, cocoon.xconf, etc.)
      a. cocoon.xconf
      b. logkit.xconf
      c. etc.
    ii) Library locations and itemization
      a. lib
      b. classes
    iii) Other

3) Architecture in depth
  a) Generators
    i) What they are and why they exist
    ii) Listing of existing generators, their usage, and examples
    iii) How to write a custom generator (with a reference to XSP)
  b) Transformers
    i) What they are and why they exist
    ii) Listing of existing transformers, their usage, and examples
    iii) How to write a custom transformer

  ...repeat this model for the other major components...

4) Best practices by use case

5) Advanced Architecture
  a) Cache store
    i) How the existing implementation(s) work
    ii) Basic steps to implement your own
  b) Sitemap logic
    i) How the existing implementation(s) work
    ii) Basic steps to implement your own
  c) Flow
    i) How the existing implementation works
    ii) -- Heh, I don't know that implementing your own is less than a 
novel --

6) Appendixes
  a) Avalon references
  b) W3C references

--------

The idea here that the first hooks the newcomer and gives them a taste 
of what's possible.  The second helps them get it going on their 
machine.  The third describes how everything works.  The fourth builds 
upon everything else to help in working, production environments.  The 
fifth is the "graduate degree" when someone is ready for committer 
status.  The last is simply relevant reference material all put together 
in one place (it's assumed that the rest of the documentation would have 
topic-specific references to parts of these).

Thoughts?

- Miles



Re: proposal: "The Newbies Competence Center"

Posted by Miles Elam <mi...@pcextremist.com>.
Tony Collen wrote:

>On Mon, 27 Jan 2003, SAXESS - Hussayn Dabbous wrote:
>
>  
>
>>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 is good. HOWEVER, occasionally the line between "user" and
>"developer" gets blurred, especially when a user realizes they need to
>develop a custom component.
>
>All too often, I've gone to the developer section looking for information
>that was actually in the user guide, and vice versa.
>
I totally agree.  In fact, this is an item that I took issue with in 
Lajos and Jeremy's book: which "Generators" section should I be looking 
in?  I also don't know that a quick reference and a manual must be 
distinct items.  For a printed book, this makes a lot of sense.  But the 
web is inherently a quick reference -- bouncing from relevant topic to 
relevant topic.  This is an area where I think the existing 
documentation (for some components) shines.  If you take a look at the 
Request XSP logicsheet 
(http://xml.apache.org/cocoon/userdocs/xsp/request.html), this is an 
example of what I mean.  If the page simply had quick, in-page links to 
description, usage, examples, and quick reference, you would be done.  A 
user looking up information says, "Hmmm, I know I want to use a 
serializer so I'll go to the serializer section."  From there, they can 
select if they want an example, an API lookup, etc.  Quick references 
exist because no one wants to haul around five hundred page books.  But 
if you are on the web, you already have access to a million page book.  
The same rules don't apply.

However, I think the above list has merit if you clearly define what 
"development" is.  I tend to think that *anyone* who installs Cocoon and 
edits something to be a developer rather than a user.  The users, in my 
mind, are the folks using the web browser.  There are, however, 
different classes of developer.  For example, if you write an XSP 
document, you've in essense written a generator.  No, they didn't call 
javac themselves, but it's only slightly different.  The difference 
mainly lies in its relative ease, not in the intent.  If you set up a 
pipeline in the sitemap, what are you if not a developer assembling 
components together?

On the other hand, making changes to the Flow engine, the cache store, 
the sitemap parser, etc. are definitely different from writing your own 
transformer.  The distinction in the documentation should be "here are 
things you can do for your own benefit that affect no one else" and 
"here are things that fundamentally affect the requirements for other 
components."

For example:

1) Architecture Overview/Primer/First Steps
  a) Why Cocoon exists
  b) Quick start installation
  c) Hello World (XSP document going through a simple transformer and 
serializing to HTML)
  d) Very brief introduction to sitemaps, generators, etc. by explaining 
Hello World

2) The Cocoon servlet
  a) Installation instructions
    i) Tomcat
    ii) Jetty
    iii) JBoss
    iv) etc.
  b) Web app layout
    i) Configuration locations (logkit.xconf, cocoon.xconf, etc.)
      a. cocoon.xconf
      b. logkit.xconf
      c. etc.
    ii) Library locations and itemization
      a. lib
      b. classes
    iii) Other

3) Architecture in depth
  a) Generators
    i) What they are and why they exist
    ii) Listing of existing generators, their usage, and examples
    iii) How to write a custom generator (with a reference to XSP)
  b) Transformers
    i) What they are and why they exist
    ii) Listing of existing transformers, their usage, and examples
    iii) How to write a custom transformer

  ...repeat this model for the other major components...

4) Best practices by use case

5) Advanced Architecture
  a) Cache store
    i) How the existing implementation(s) work
    ii) Basic steps to implement your own
  b) Sitemap logic
    i) How the existing implementation(s) work
    ii) Basic steps to implement your own
  c) Flow
    i) How the existing implementation works
    ii) -- Heh, I don't know that implementing your own is less than a 
novel --

6) Appendixes
  a) Avalon references
  b) W3C references

--------

The idea here that the first hooks the newcomer and gives them a taste 
of what's possible.  The second helps them get it going on their 
machine.  The third describes how everything works.  The fourth builds 
upon everything else to help in working, production environments.  The 
fifth is the "graduate degree" when someone is ready for committer 
status.  The last is simply relevant reference material all put together 
in one place (it's assumed that the rest of the documentation would have 
topic-specific references to parts of these).

Thoughts?

- Miles



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


Re: proposal: "The Newbies Competence Center"

Posted by Tony Collen <tc...@neuagency.com>.
On Mon, 27 Jan 2003, SAXESS - Hussayn Dabbous wrote:

<snip/>

> 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 is good. HOWEVER, occasionally the line between "user" and
"developer" gets blurred, especially when a user realizes they need to
develop a custom component.

All too often, I've gone to the developer section looking for information
that was actually in the user guide, and vice versa.

One thing I'd like to see, at least for the "production" docs, is to have
the API Javadocs up front and center.

I may have mentioned this one last time the issue of docs came up, but
here's another thing that confused me:

(Taken from xml.apache.org/cocoon/):

Documentation
  Introduction
  Installing
  Overview
  User Guide
  Dev Guide
  Tutorials
  FAQs
  How-Tos
  Performance
  Snippets
  ToC

Ok, Introduction and Installing are good, and Overview I can understand.
Perhaps these are a little out of order.  Now the problem is, where do I
go to in order to find out how to strip out my sitemap?  There's a User
guide, Tutorials, FAQs, and How-to's, which all sort of could be the same
thing.. especially "Tutorials" and "How-tos".  Snippets could also be
considered how-to, but also probably tutorial.  The same goes for the
"performance" section.

Basically, what I see needs to be done, is we need all of this info
consolidated into one place.

Remember, the docs are for the users, and unfortunately, the developers
might have a different idea about how the information "should" be
categorized.    Or maybe our problem is making the distinction between
"users" and "developers" ...  I would guess that eventually, most users
become developers, so then, it's just a matter of "beginning user" vs.
"power user", and so on.



Tony

--
Cocoon: Internet Glue (A Cocoon Weblog)
http://manero.org/weblog/



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


Re: proposal: "The Newbies Competence Center"

Posted by Tony Collen <tc...@neuagency.com>.
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:     <co...@xml.apache.org>
> For additional commands, e-mail:   <co...@xml.apache.org>
>
>


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