On Jun 3, 2005, at 8:42 AM, Mark Leicester wrote:
What is Apache Cocoon?
Apache Cocoon is an MVC web application framework uniquely suited
to XML publishing.
Apache Cocoon is founded on the principle of separation of
concerns. Cocoon's Avalon-based component architecture makes it
easy to create web applications from reusable components. You use
the Cocoon Sitemap to assemble components into pipelines. Pipelines
react to client requests, generating information from a source,
transforming it, before serializing it back to the client in the
desired format. This separation of concerns between generation,
transformation and serialization, allows the same source to be
served up to your browser, cellular phone or printer, or to be
consumed by your web service.
In addition to this mature publishing framework, Apache Cocoon
offers features and frameworks to help you build full-featured web
applications. Cocoon Flow offers continuation-based scripting for
your application business logic. Cocoon Templates offer dynamic XML
generation. The Cocoon Forms framework greatly simplifies client
interaction with a growing library of user interface widgets for
your web application forms.
Mark, I applaud your efforts to improve Cocoon's documentation and I
am thankful for your company footing the bill. However, I think what
you have written above just continues the existing problem with a
different set of words. The two paragraphs as a whole assume
familiaraity with the concepts of MVC, separation of concerns, that
Cocoon has a sitemap and what that is, pipelines, generation,
transformation and serialization and continuation-based scripting. If
I were completely unfamiliar with Cocoon, I really still would not
know what it is other then a web application framework.
I spent last weekend going over Cocoon's documentation, various
threads concerning it and proposed TOCs. I came away with the feeling
that Cocoon's documentation is written by experienced Cocoon
developers for experienced Cocoon developers. The only thing Cocoon's
documentation should assume is that a user is familiar with XML and
XSLT. If they want to use flow the documentation needs to assume that
they have some familiarity with javascript and/or Java. Its similar
for each aspect of Cocoon. Assume only enough to go forward with out
having to explain things outside of Cocoon.
I have an email that I have been working on since Monday with an
outline of how I was planing to proceed with writing new
documentation. Key aspects are that we need to have separate
documentation for users and developers and that the user
documentation needs to assume as little as possible about the users
experience. Hopefully, I will edit down to a few paragraphs and send
it this weekend.
In the meantime you might want to consider targeting your
documentation for the most junior and least skilled website developer
in your company. Better yet, a 1st year student.
I mean all this in the most constructive way. Hopefully we will be
able to collaborate over the next 4 weeks and get a good start on
rewriting these docs.
Glen Ezkovich
HardBop Consulting
glen at hard-bop.com
A Proverb for Paranoids:
"If they can get you asking the wrong questions, they don't have to
worry about answers."
- Thomas Pynchon Gravity's Rainbow
