cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Glen Ezkovich <gez...@cox.net>
Subject Re: [Docs] A proposed revision, four weeks for Cocoon, and a smattering of Julie Andrews
Date Fri, 03 Jun 2005 22:39:21 GMT

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


Mime
View raw message