documentation issues (guides, hint, error retrieval)

[SAXESS - Hussayn Dabbous <da...@saxess.com>]

Hello;

I want to adress three serious and tightly coupled issues
concerning development and deployment of webapps using
cocoon. All related to documentation:

1.) The application developers viewpoint
2.) The administrators viewpoint
3.) The cocoon error reporting issue

But i do not want to adress issues and let things open
for others. I could help getting things done, if it's not
already adressed by someone else of course.
But also then i would need a guide...


========================================
1.) The application developers viewpoint
========================================

I feel a bit lost in the "cocoon hyperspace". I can find
a huge bunch of information in the docs. Many things
been described there seem to be of high relevance. The infos
given there all are quite understandable on themselves, but
nowhere i can find infos, under which circumstances i should
really use which part of cocoon to solve my problems. Yes i
know about cocoondev.org and i use the infos stored there and
i am happy with this, yes i read some very interesting articles
especially those from s&n, (good stuff). I did not (yet) read
the books published about cocoon though...

Currently i start reengineering a JSP/XML intermixed webapp
using the cocoon framework and i constantly ask myself
following questions (concerning cocoon usage):

1.) It works, but is it how it was intended?
2.) What are the consequences of choosing this aproach?
3.) Will i fall into a trap, if i move further this way?

I could start tweeking around with every aspect of the
framework, until i understand the nuts and bolts in deepest
detail. Then i could decide, which approach i'd choose best
for my app. Maybe things must be done this way. But i am
afraid, doing this on my own would take too long time.

Instead i appreciate some guideline, that allows me to
start using cocoon in a "simple, but effective way", so
i can jumpstart into production, without all the time
asking myself, if i am on the right trail. Then after
some time when i was leaded to the more complex issues
i start learning howto use the framework, but all the time
i keep beeing productive...
By the way, i was really happy with the "bonebreaker" example.
I like such an approach.

================================
2.) The administrators viewpoint
================================

When deploying my app to the customer, i will need to document
not only how the app works, but also how it is customised.
OK, i have to write an application specific administration manual.
But i don't want to reexplain, (e.g.) how cocoon sitemaps work
and so on. On the other hand i can't give them the (current)
cocoon docs, because they will get lost even more (they are no
programmers after all ;-)

I would appreciate some sort of HOWTO concerning customization,
which could be sorted by "components", or "strategies" or
"keywords", or completly different (Maybe this "wiki approach"
is good for this?) Then i would refer to this in my apps,
like: "the sitemaps concept is briefly explained here and there"...
Actually for the sitemaps this "howto" already exists thanks a lot
to the author ;-)



====================================
3.) The cocoon error reporting issue
====================================

Eventually my customers will want to add their own stuff
into the webapp. But then things get really a mess (in my eyes):

I constantly ask myself, why is cocoon so bad in error reporting?
After some time of investigation i managed to learn how i
have to interpret several stack trace patterns. I simply start
"getting the feeling" how to isolate the error cause from several
hundreds of trace lines all usefull for programmers but completely
useless for admins...

I asked some days ago, why it is so problematic to report an error
during an xslt transformation back to the browser.
Why can i find the errors reported in error.log (after digging deep)
but the pipeline (sometines) fails to report this to me?
In general errors reported back tend to be not well understandable
although in some cases looking at the error.log reviels much more
concrete infos about the error cause...

And even worse: For errors produced in a <map:part>
the only way to even get AWARE of them is looking into error.log
In general the only clue to an error occured is that i see nothing
on the screen. This could be really a nightmare for the admin.
By the way, since i plugged in saxon instead of xalan, my local
cocoon documentation all renders empty pages (of course no errors
on the pages -> a naive admin would then state, the page is empty,
"ok no docs available yet?" aaarghh ;-)

OK, you could claim, cocoon is not an authoring tool, and getting
the XSLT's ready for production should be done outside of the
framework. But this is not a good approach in general, because you
simply have to take the application into account. Consider you have
tested your XSLT outside of cocoon and everything worked fine in your
testbed. Then you switch to cocoon and nothing goes...
How would you proceed then?

I would appreciate a solution for the error reporting problematic.
If nothing else goes i could think of a weird thing like an error
interpreter component that simply does some intelligent "error minig"
in the logs ;-) e.g. looking for patterns ...

regards, hussayn


-- 
Dr. Hussayn Dabbous
SAXESS Software Design GmbH
Neuenhöfer Allee 125
50935 Köln
Telefon: +49-221-56011-0
Fax:     +49-221-56011-20
E-Mail:  dabbous@saxess.com




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