cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Upayavira>
Subject Re: "Apache Cocoon in Action" suggestion and call for opinions
Date Wed, 13 Apr 2005 08:30:03 GMT

I know Reinhard has said a lot already. I just wanted to make a few 

1) Thanks for coming over to the dev list. It is the best place for 
these discussions as all developers will be reading what it said.

2) What myself and Reinhard have conceived is a container for ALL docs. 
We need first of all to bring the reference docs across, and to scrap a 
lot of the crud that has built up over the years. That, I hope, will 
establish a foundation upon which we can build more howto and tutorial 
like docs.

3) I completely agree with you that such walkthrough docs are completely 
necessary and the work I have done with Reinhard very much takes that 
into account. We just haven't yet conceived of exactly what form those 
docs will take, and your assistance (and that of others too) is most 
welcome in crafting this side of our documentation. So long as we can 
keep it cohesive, then the more the better.

Thanks for your comments, and I look forward to seeing what you come up 

Regards, Upayavira

Sebastien Arbogast wrote:
> Hi,
> I may have something to suggest concernig the new documentation effort.
> The main problem that I had to face while begining to work with Cocoon
> was the enormous gap between the level of the first tutorials I found
> on the wiki or other sources like or IBM
> DeveloperWorks. I mean those detailed articles about particular
> features of Cocoon are very useful as a reference when you know how to
> use Cocoon  but it's very difficult to integrate things when you are a
> beginner. And it's even worse with samples because either they make a
> lot of basic assumptions to fit precisely what's said in the parallel
> documentation or wiki article, or we get enormous technology
> demonstrations like CHS, which are very difficult to dive into.
> And as it seems, the new documentation effort is mainly aimed at
> reviewing and reorganizing existing articles and then filling the gaps
> with missing articles. The result of that process will be at best a
> wonderful reference, but it won't solve this gap between "getting
> started" stuff and everyday-work with cocoon.
> So my suggestion is the following : all the technologies I've learnt,
> Java in first, I've learnt them thanks to some great books based on
> case studies explained in parallel with theoretical issues, in order
> to apply things concretely and progressively as you discover and
> understand them, while building a common application by aggregation.
> Sort of a big tutorial like you can read them in Hibernate in Action
> or J2EE tutorial for example.
> The objectives/topics that should be covered in such a "Apache Cocoon
> in Action" tutorial could be :
> 1st part : Getting started with Cocoon
> - What is Cocoon ? History and theory
> - Installing Cocoon on Tomcat : building process, blocks description etc.
> - Hello Cocoon : classical but always efficient to demonstrate and
> reassure people...
> - Integrating Cocoon into your development environment :
> application/web server, source versioning control, build tools (ant or
> preferably maven), IDE (eclipse and tools like xml editor,
> anyware-tech plugins, etc.), information sources (mail lists,
> websites, etc.)
> - Case study presentation : goals to achieve, overview, etc. the exact
> nature of this case study is still to determine but I think it has to
> be as common as possible. For example it could be a complete website
> with a backend
> 2nd part : describing the basic concepts and giving links to the new
> reference for details each specific feature. Each chapter would end
> with integration of concepts into the case study
> - sitemap concepts + matchers, readers, protocols, modules
> - generators + quick introduction to XML
> - transformers + quick introduction to XSLT
> - serializers + quick introduction to XHTML/CSS
> - resources and views
> - flow control inside the sitemap : selectors, redirecting, error
> handling, actions,etc.
> 3rd part : advanced concepts making it possible to optimize things, to
> improve performance and accessibility of the case study application
> - caching
> - internationalization
> - forms (with an overview of the different forms technologies, not
> only CForms, in order to understand why CForms are a good choice)
> - control flow (with a introduction to apples if possible)
> - XSP and logicsheets
> 4th part : integrating Cocoon with other tools to add a backend to the
> sample application
> - authentication framework to protect the backend
> - introduction to Java, design patterns and avalon
> - introduction to Hibernate and AndroMDA for data representation using
> an embedded HSQLDB database + integrating Hibernate into Cocoon
> - advanced CForms and control flow to edit Java Beans
> - integrating other blocks with small introduction samples for axis,
> batik and other interesting blocks
> .....
> This is just a suggestion and I obviously miss many things because
> I've been working with Cocoon for only a few months, but I think that
> this content should help people to fill in the gap and getting to know
> that wonderful tool better.
> Moreover this documentation could be written and reviewed in parallel
> and tight collaboration with the new Cocoon 2.2 documentation effort
> to make sure that the information is accurate and exact and to keep
> stuff in sync. And it could be written and reviewed/corrected
> progressively with the help of users giving feedback about what's
> missing and what should be removed.
> What do you think ? 
> Would anyone be interested in helping me to write such a documentation ? 
> Do you have ideas about technical infrastructure we could use : wiki,
> mail lists, maybe forums and IRC channel which are ideal for user
> feedback and easy communication, documentation format (forrest, SVN
> repository, writing and reviewing process) ?
> What about work team organization (I find this very important to avoid
> stepping over each other's feet and make sure everything is correct
> and precise, even if it's longer) ?
> What about translations : would some people interested in translating
> that documentation to other languages as we write it (french ? spanish
> ?) maybe a few polls on local development communities would be
> necessary to determine what languages are worth translating to.
> What about a common website area to centralize efforts and make the
> project known to users and potential writers ?
> Maybe it's not necessary to talk about the content in the first place,
> to insist on whether or not it would be interesting and if some people
> are willing to participate, and what could be the general shape of
> such a project...
> I'm waiting for your opinions. 
> FTR, I should precise that right now I'm working on a big project
> using Cocoon as its core XML server and it's my first project using
> Cocoon, which implies that
> -> I won't be able to spend my whole days on this
> -> I don't have much knowledge about Cocoon
> which means that even if I intend to use my newbie aspect to make the
> documentation accessible and my great interest in Cocoon to make this
> documentation successful, we would need many interested
> diverse-skilled people to bring this to realty in a reasonable time
> (that is before Cocoon 4 at least ;o)
> Regards
> --
> Sebastien ARBOGAST

View raw message