cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Mark Leicester <>
Subject Re: [Docs] A proposed revision, four weeks for Cocoon, and a smattering of Julie Andrews
Date Sat, 04 Jun 2005 05:05:55 GMT
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,, 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.

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".

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, 

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

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


> 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
> 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