cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Glen Ezkovich <>
Subject Re: [Docs] A proposed revision, four weeks for Cocoon, and a smattering of Julie Andrews
Date Sat, 04 Jun 2005 21:12:10 GMT

On Jun 4, 2005, at 12:05 AM, Mark Leicester wrote:

> Hello Glen,
> Thanks for your comments! They are indeed constructive, and you are  
> right to raise this issue. Who are we writing for? In simplistic  
> terms I imagine two groups: fairly-technical and not-so-technical.  
> My solution has been to create one site, http:// 
>, for the not-so-technical market, and another,  
>, for the fairly-technical market.  
> Spread Cocoon is modelled on It's for  
> people who want to know about Cocoon, want to know how it can help  
> them, want to hear success stories, see example sites, know about  
> Cocoon events, and generally buy badges, posters, stickers and T- 
> shirts. On the other hand, Planet Cocoon is a rich developer  
> community site where technical people can find the nuts and bolts,  
> and get on with being creative. Firefox has similarly separated  
> sites, and I believe the same two-pronged approach may work for  
> Cocoon.

We are talking about two different things here. An evangelical site  
is not the same as a novice site. When we talk about Cocoon users we  
are still talking about developers. This most certainly isn't the  
case with Firefox users. What I see as the problem, is that the  
current documentation assumes a familiarity with both the theories  
that led to the development of Cocoon and to some extent Cocoon  
itself. (you can find the explanations, but then you get taken off  
the path which you were previously following [1]) Someone new to web  
development would have a hard time understanding the documentation.  
Even experienced developers who were working within a different  
framework would have some difficulty in understanding the usefulness  
and purpose of Cocoon and some of the various pipeline components.

Its been repeated in several threads concerning documentation and  
marketing that Cocoon appears as some huge scary beast. While its  
true that the Cocoon distribution has many components and multiple  
ways of accomplishing similar tasks, even the most complex pipeline  
is pretty simple when compared to a JSP that performs the same tasks.  
The documentation should show how simple its to gather data from  
various sources and present it to users (human and computer) in  
multiple yet consistent ways.

In order to convince developers that Cocoon is both simple and  
powerful the documentation needs to consider both the novice and the  
experienced developer. That means that explanatory text needs to  
assume only minimum knowledge of web development technologies and  
theories employed by Cocoon. In order to be accessible to novices  
simple examples need to be given. In order to be of value to  
experienced developers use cases need to be presented and realistic  
examples which solve the problem should be provided. Along with all  
of this the documentation needs to also serve as a reference so that  
a developer can quickly and easily find the information they need.

That said, there is room for other types of documentation. i.e.  
tutorials, recipes, etc. that target various levels of skill. The  
main point is that when a user, novice or expert, looks in the main  
set of documentation, they find something that at least explains and  
demonstrates the aspect of Cocoon in which they are interested, in  
such a way that both are satisfied. The one thing I hate is a trivial  
example that does not scale as the problem gets slightly more  
complex. What I used to hate was an example that was more complex  
then I could understand.

> This text is targeted at Planet Cocoon: experienced developers,  
> wanting to know more, perhaps weighing up Cocoon as a possible  
> solution alongside other web application frameworks. Let's get this  
> text right for developers. We can tailor it further for different  
> types of developers, like "Click here if you want to compare Cocoon  
> with Struts", "Click here if you want to compare Cocoon with .NET",  
> "Click here if you are a 1st year student who wants to change the  
> world".

Thats fine. It will allow them to compare Cocoon to other frameworks  
or become more involved with the Cocoon community. What it won't do  
is explain the concepts.

> For the equivalent high-level paragraphs on Spread Cocoon, I can  
> imagine wholly different language oriented to the non-technical  
> public. Let's develop a version of this text for the general,  
> thrill-seeking, public.

OK, do you know of anyone who accesses a cocoon driven site and who  
is not a developer and who cares that the site is built on Cocoon?  
Anyone who is going to access a site devoted to Cocoon, is most  
likely a developer.

> Please remember that neither of the efforts I am discussing are in  
> any way official, or representative of the views of the Cocoon PMC.

I remember. I'm not that old that my short term memory is shot.  
(close but not yet) :-)

> You are quite right: it's about knowing your audience. I am looking  
> forward to hearing what you and others have to say!

I'm not going to say as much as I planed. I'm working on keeping my  
mouth shut. Seriously, I want to get started on improving the  
documentation. I'll be sending an email outlining the direction in  
which I'll be heading. Unfortunately, I won't be getting paid to work  
on this so the time frame is a bit of a question.

[1] takes you to from which  
you must go back to user documentation to continue.

Glen Ezkovich
HardBop Consulting
glen at

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

View raw message