cocoon-users mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Miles Elam <>
Subject Re: proposal: "The Newbies Competence Center"
Date Mon, 27 Jan 2003 21:04:37 GMT
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 

> 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 

> 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 
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.     <>

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

View raw message