cocoon-users mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Derek Hohls" <>
Subject Re: proposal: "The Newbies Competence Center"
Date Tue, 28 Jan 2003 07:17:29 GMT
Miles makes some important points below:
- We need to say - upfront - where and why Cocoon should *not* be used
- We need to define a typical skills set for a Cocoon project team (as
as define a minimal knowledge set for getting started!)
- We *do* need to split off the 'tips and tricks' from the basic
(... the example below says one has to know how to do caching of XSPs'
I still do not know how to do this but fortunately no one has yet
about the speed of the generators - to me the issue is optimizing the
of the transformers - anyone tried doing DocBook on the fly?? -- but
point is here is that you dont' need to know this stuff in order to get
optimization is a second or third order stage of learning)

- The learning path is a brilliant idea - like a "trail map" of sorts
that outlines
where you might be going to (or be expected to learn) - my own is very
but the order was (and still might be) a little different:
0) Finding out abvout XML and XSLT
1) Learning what makes Cocoon different and the general concept of 
a sitemap.
2) Then the concept of a pipeline 
3) Then seeing what components are available ("Wow!  I can create and
test single tranformation pipelines and then compound them using
include statements in my XML - cool!) 
4a) Learning XSP to make simple items.
4b) Learning ESQL to work with databases
4c) Learning Actions to manipulate sitemap pathways
5) Then bumping into the wall of "I need to do X but I don't see a 
ready-made component yet."
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 4c now...  and at each stage I get new insights
just how powerful and essential the sitemap is.  

>>> 27/01/2003 11:04:37 >>>
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
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
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
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
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
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

> 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

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 

> another argument was: the user does not deal with internals nor with
> philosophy under the hood (like avalon framework, etc.) The
> 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
> 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
a sitemap.
2) Then the concept of a pipeline 
3) Then seeing what components are available ("Ooh!  I can create a 
directory listing as XML and use and include transformer to drop them
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
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,
-- 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
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.     <>

To unsubscribe, e-mail:     <>
For additional commands, e-mail:   <>

This message has been scanned for viruses and dangerous content by 
MailScanner, and is believed to be clean.

"The CSIR exercises no editorial control over E-mail messages and/or
attachments thereto/links referred to therein originating in the
organisation and the views in this message/attachments thereto are
therefore not necessarily those of the CSIR and/or its employees.  
The sender of this e-mail is, moreover, in terms of the CSIR's Conditions
of Service, subject to compliance with the CSIR's internal E-mail and 
Internet Policy."

View raw message