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>