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
well
as define a minimal knowledge set for getting started!)
- We *do* need to split off the 'tips and tricks' from the basic
knowledge
(... 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
complained
about the speed of the generators - to me the issue is optimizing the
speed
of the transformers - anyone tried doing DocBook on the fly?? -- but the
point is here is that you dont' need to know this stuff in order to get
started;
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
similar
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
(generators-to-tranformers-to-serializers).
3) Then seeing what components are available ("Wow! I can create and
1) 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 ("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.
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."
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 into
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 into
just how powerful and essential the sitemap is.
>>> [EMAIL PROTECTED] 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 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: <[EMAIL PROTECTED]>
For additional commands, e-mail: <[EMAIL PROTECTED]>
--
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."
