Mailing-List: contact users-help@cocoon.apache.org; run by ezmlm
Precedence: bulk
Reply-To: users@cocoon.apache.org
Mime-Version: 1.0 (Apple Message framework v613)
In-Reply-To: <40900FF0.9040704@umn.edu>
References: <s08fc4d9.006@cs-emo.csir.co.za>
 <66ED677D-994F-11D8-BAB7-000A95A556A2@highpoweredmutant.net>
 <40900FF0.9040704@umn.edu>
Content-Type: text/plain; charset=US-ASCII; format=flowed
Message-Id: <DAFA2C3B-9968-11D8-BAB7-000A95A556A2@highpoweredmutant.net>
Content-Transfer-Encoding: 7bit
From: Brent Fitzgerald <burnto@highpoweredmutant.net>
Subject: Re: Cocoon: Language Babel -or- Database Development Platform ?
Date: Wed, 28 Apr 2004 16:07:43 -0700
To: users@cocoon.apache.org

Hi Tony,

Thanks for asking.  I see where you are coming from.

Well first let me emphasize that I don't mean to criticize Cocoon or 
its documentation.  I really like Cocoon, and in fact I think I have a 
weird sort of affection for it.  The whole project is great, and I 
truly appreciate all the efforts of the many talented contributors.  
And I actually think that Cocoon's documentation is quite good, 
especially when compared to some other open source projects.

That said, Cocoon also feels very complex and open-ended from a user's 
perspective, and sometimes the line between cocoon user and cocoon 
developer is sort of blurry.  Who *is* the cocoon user, and what sort 
of prerequisites are really assumed?
>
> What documentation exactly?

I pretty much use the main Cocoon site, especially the User Guide.  
Also: the Wiki of course, this list (and its searchable archives at 
MARC), CocoonCenter, and the local samples.

> What sort of documentation are you looking for?

If I search the Wiki I can learn a lot, but I have to know what I'm 
looking for.  When you are starting to learn about something totally 
new, you don't even know what questions to ask.  It might be that 
everything I need is out there, but it all feels scattered.

>
> What would help you find the information that you need?

The Wiki has a lot of information, but because it is a Wiki and its 
organization is loose it just doesn't feel entirely credible compared 
to the "official" documentation.  Others may disagree.

The official docs cover most of the concepts and the components in the 
release, but there isn't much context.  A better repository of 
user-oriented tutorials would be wonderful, especially if new ones were 
released regularly on the official Cocoon page, sort of like how 
o'reilly does it on XML.com.  A tutorial can pull together several 
concepts, highlight new features, and spark new ideas.  The main Cocoon 
site's tutorial section is skimpy.  CocoonCenter is sort of doing this 
already, but it would be nice to see  more on the cocoon site.  The 
Wiki has a few tutorials, but they are really only for real beginners.

> I'm not trying to be confrontational at all, I'm really curious about 
> these defficiencies, and I'd like to see through the eyes of a true 
> user.

When pressed it is hard for me to put my finger on particular 
deficiencies.  I guess a lot of the docs just feel immature.  For 
example, take a look at the Session Context page 
(http://cocoon.apache.org/2.1/developing/webapps/contexts.html).
- The linking is screwy.  I clicked on Session Transformer in the 
Transformers section in the User guide, but now I am suddenly in the 
Developer guide.
- Coming from 2.0 I thought the session stuff was some sort of 
sunshine/sunspot thing, and this page doesn't even mention that.  A 
little bit of history or something would be nice.
- Nothing in this section mentions flow or woody, both of which I 
assume would be useful in developing a webapp.

These sorts of inconsistencies are not hugely significant individually, 
but cumulatively it can make for some confusion.

> Again, what are the new pieces that you are referring to?  I have to 
> agree with you about good docs being essential to a tool.
> Also, please see http://wiki.cocoondev.org/Wiki.jsp?page=Cocoon215TOC, 
> and feel free to add or change stuff you think that needs to be there, 
> or restructured.

Thanks for pointing this out.  This looks helpful.  I've never tried 
working on the Wiki content, but maybe I should give it a try.

At the risk of seeming overly warm and fuzzy, the coolest thing about 
Cocoon is that it encourages a different methodology for developing a 
site.  To learn Cocoon you have to shift your thinking away from some 
of the more traditional web systems paradigms.  I feel that Cocoon has 
a really good, quirky, "think different" attitude that other frameworks 
like struts or turbine lack.

But very little of the documentation reflects this attitude.  The 
official cocoon site doesn't reflect this feeling either.  The 
attention of the Cocoon user community is decentralized, spread among 
the official site, the Wiki, and the user list.  So the documentation 
feels spread apart too, and there is a lot of emphasis on nuts and 
bolts, but not so many 'bigger picture' tutorials that teach and 
encourage Cocoon design methodology.  It would be great if the Cocoon 
site was a little more worthwhile as a destination, where someone can 
regularly check for new tutorials or articles, see if there are any 
news or updates, maybe look for and download new components.

Obviously that's a lot to ask, and for now I am still managing to pick 
up what I need, which is what it really comes down to.  It just isn't 
too centralized or organized at this point.  Agree?  Disagree?

Thanks,
Brent

--
http://www.brentfitzgerald.com/


---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@cocoon.apache.org
For additional commands, e-mail: users-help@cocoon.apache.org