cocoon-users mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Liam Morley <lmor...@gdc.wpi.edu>
Subject Re: Giving up! Cocoon too big, slow and confusing
Date Sat, 29 Jun 2002 07:17:26 GMT
To be fair, the documentation has greatly improved since I started with 
Cocoon (almost a year ago). I sent out an email earlier with specific 
comments (thank you Nicola for noticing:)), both the good and the bad.. 
and while I was looking through the existing documentation, I noticed a 
few things I hadn't noticed before.

Here are the best answers for the specific questions that I've been able 
to come up with, hopefully they're helpful.

Ricardo Trindade wrote:

>Ok. Where is the documentation for Pipeline Components ?
>
>Where is an in-depth description of each type of G enerator ?
>
By pipeline components, do you mean sitemap components? You can find 
that (as well as in-depth descriptions of most Generators) at 
<http://xml.apache.org/cocoon/userdocs/index.html>. From the front page, 
you can just click on "User Guide" on the left and you'll get there. You 
might want to take a look at the Internal Pipeline snippet 
<http://xml.apache.org/cocoon/snippet/snippet-internal-pipeline.html> 
from the "Snippets" section, or the Sitemap documentation 
<http://xml.apache.org/cocoon/userdocs/concepts/sitemap.html> located in 
the "Concepts" section of the User's guide. (I think because the sitemap 
is so central, you might want to think about taking it outside of the 
concepts section and moving it into the main User Docs section? I don't 
intuitively look in the "Concepts" section for the sitemap 
documentation, that might just be me, though.)

>There is no depth to the documentation. One doesn't have to go very far
>to run out of documentation.
>
In my mind, that's what this process is for; to find out the trouble 
areas and fix them. And as you've pointed out, depth is one of those 
trouble areas. One of my problems was the consistency; some docs really 
explained both the problem and the solution extremely well, while others 
just gave me a fully qualified classname, a one-sentence description, 
and whether or not it's cacheable (sometimes with a number of ?'s 
instead). But in the near future, if I can fully wrap my mind around 
some of these concepts enough to consider myself worthy of doc writing, 
I'll do so.

>The Tutorial. How do I write a simple data-base backed application ?
>
One of the problems in the doc that I just noticed now is how hard it 
can be find something that you're looking for. I was just 12 hours ago 
that I had looked over the entire site, and I saw a really nice 
cocoon-specific database article. But now I can't remember if it was a 
how-to, a faq, or a tutorial. I think that's a problem... and my only 
suggestion on how to fix that is to either change the wording or make it 
really clear what goes in each, as well as edit gray areas. Taking a 
quick look through the site, however, I found the following:

Dev Guide - Using Databases in Apache Cocoon
(I thought the Dev Guide was for those who were developing Cocoon, not 
developing with Cocoon? the line seems blurry to me.. I find the javadoc 
from the Dev Guide useful, however I find the docs in the Users Guide 
useful as well.. I don't see the need for a seperation, and I find the 
seperation both confusing and time-consuming to repeatedly move from one 
section to the other.)
<http://xml.apache.org/cocoon/developing/datasources.html>

Users Guide - Concepts - Database Access
(This one's a bit hard to find, I think; I ended up looking three times 
in the How-To, FAQ, Tutorial or Performance section. The concepts 
section doesn't stick out so well in my mind.)
<http://xml.apache.org/cocoon/userdocs/concepts/databases.html>

I can't promise that these are what you're looking for, but hopefully 
it's a start. And hopefully, if they're not what you're looking for, the 
questions that get raised will become questions posed to the list.

all the best,
Liam Morley


---------------------------------------------------------------------
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:     <cocoon-users-unsubscribe@xml.apache.org>
For additional commands, e-mail:   <cocoon-users-help@xml.apache.org>


Mime
View raw message