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