Proposal for new introductory page of Cocoon documentation

[H....@MI.unimaas.nl]

Guys, 

Please improve and extend the following text. The intention is provide
people enough information to decide whether Cocoon is the right choice for
their problem/project.

Bye, Helma

---
The Apache Cocoon project

This introduction to Apache Cocoon is intended to highlight some of its
unique features and to help decide if it is suited for your purpose.

Apache Cocoon

Apache Cocoon is a web development framework built around the concepts of
separation of concerns and component-based web development.
Cocoon implements these concepts around the notion of 'component pipelines',
each component on the pipeline specializing on a particular operation. This
makes it possible to use a Lego(tm)-like approach in building web solutions,
hooking together components into pipelines without any required programming.
Cocoon is "web glue for your web application development needs". It is a
glue that keeps concerns separate and allows parallel evolution of all
aspects of a web application, improving development pace and reducing the
chance of conflicts.

The Apache Cocoon Project

The Apache Cocoon Project is the open source community project developing
Apache Cocoon and Cocoon-based application frameworks. With strong
foundations in XML-based server-side web application frameworks, the Apache
Cocoon Project consists of a group of people that share common values on
collaboration-intensive and community-based quality open source development.
The Apache Cocoon Project is proud to share these values with its parent
organization: The Apache Software Foundation.

When to use Cocoon?

The flexibility of Cocoon is best used in situations where documents have
multiple sources and/or should be presented in different ways. In this
context source is a generic concept. It might be a document management
system, a database or even user data entry through web pages, previously
built by a Cocoon pipeline.

When not to use Cocoon?

Cocoon doesn't provide a point & click interface to web building. 
Cocoon is also not intended for pure static documents that are already HTML
pages at the source. For that Apache HTTP server is more suited.

Requirements for Cocoon?

Hardware/platform

Cocoon is written in Java as a servlet. To set up a Cocoon-based web
application you therefore need Cocoon, running in a servlet engine, with an
optional front of an HTTP server. The operating system is of lesser concern.
The hardware requirements should meet the requirements of large Java-based
applications.

Skills

To properly use Cocoon your skills should include at least average to
in-depth knowledge of XML and XSLT. Knowledge of Javascript is necessary
when using forms and knowledge of Java is required when non-standard tasks
should be performed. This could be extending Cocoon components or connecting
data sources that cannot be connected using the available methods.

Re: Proposal for new introductory page of Cocoon documentation

[David Crossley <cr...@apache.org>]

H.vanderLinden@MI.unimaas.nl wrote:
> Guys, 
> 
> Please improve and extend the following text. The intention is provide
> people enough information to decide whether Cocoon is the right choice for
> their problem/project.

Oh good on you Helma, great idea. I will comment in more detail later.

Where do you see is the position for this in the Cocoon docs?
I reckon a menu link at the top-level straight after the "Welcome".
Not sure what the label should be yet.

We need to fine-tune the Description paragraphs. We use them in
various places in our docs and on some other websites, e.g.
http://www.apache.org/foundation/projects.html
We need to synchronise these.

Also we should have a few links in this page to some other
relevant docs, e.g.
http://cocoon.apache.org/2.1/features.html

Thanks again.

--David