[CROSSPOST] Apache Cocoon in Action suggestion

[Sebastien Arbogast <se...@gmail.com>]

NB : this is a crosspost from Cocoon dev list. If you want to read the
answers to this first message please go there and if you have comments
or answers for this message, please post your answers to
dev@cocoon.apache.org as it will keep only one thread for this
suggestion.

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 theserverside.com 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

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

Re: [CROSSPOST] Apache Cocoon in Action suggestion

[Reinhard Poetz <re...@apache.org>]

Sebastien Arbogast wrote:
> NB : this is a crosspost from Cocoon dev list. If you want to read the
> answers to this first message please go there and if you have comments
> or answers for this message, please post your answers to
> dev@cocoon.apache.org as it will keep only one thread for this
> suggestion.

see http://marc.theaimsgroup.com/?t=111336906800002&r=1&w=2

-- 
Reinhard Pötz           Independent Consultant, Trainer & (IT)-Coach 

{Software Engineering, Open Source, Web Applications, Apache Cocoon}

                                        web(log): http://www.poetz.cc
--------------------------------------------------------------------


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