You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@cocoon.apache.org by Matt Whipple <ma...@mattwhipple.com> on 2009/11/30 14:07:16 UTC
Cocoon documentation
I'm a recent transplant to Cocoon (and Java), in particular because
Cocoon 3 appears as though it is/will be closely in line with my own
perspective on web application development. I'm interested in
contributing to the development of the framework itself, but likely
won't be able to produce anything remotely useful for a couple months
as I familiarize myself with all of the related technologies.
I've just read some of the attacks on the poor documentation of the
project and the resulting difficult entry for those unfamiliar. This
is, of course, easily confirmed by the combination of woefully out of
date references and dead links on the Web site (i.e. to the Daisy
site). As I am (obviously) hopeful to see Cocoon succeed, I certainly
don't want it to become mired in isolation like so many good projects.
As such I'd like to try to contribute some documentation. Is there any
idea among the community as to where documentation should end up, or
should I just create a new site? Also, I'd lean towards focusing on
Cocoon 3, as having documentation in place for a new release would
likely have larger impact than attaching possibly overdue docs to an
older, in the process of being superseded one. This would be premature
if there's no foreseeable beta....
Re: Cocoon documentation
Posted by Jos Snellings <Jo...@pandora.be>.
Yes, that would be it...
agreed.
On Tue, 2009-12-01 at 06:23 -0500, Matt Whipple wrote:
> Jos Snellings wrote:
> > The documentation of cocoon-3 can be checked out as:
> > svn co http://svn.apache.org/repos/asf/cocoon/cocoon3/trunk/cocoon-docs\
> >
> I stumbled upon the HTML deliverable of that on
> http://people.apache.org/~reinhard/c3-ref/html/ after sending my email.
> I'd think it would be best if the official documentation focused on
> being primarily a comprehensive reference with a quick bootstrap guide.
> A community documentation site could then supplement that with all the
> typical tutorials/how-to's and tips & tricks which gets the reader where
> he wants to be with a straightforward, minimalist approach which then
> references the official docs and other more enlightening sources.
> Regular articles/blog entries could then highlight the activity in the
> community, and the possibilities of various Cocoon components could be
> showcased. Guides to all of the overlapping processes which can be
> [easily] extrapolated from existing material can be given a home so that
> a potential new developer with a specific need is provided with an
> apparent foot in the door. Basically a site which presents a welcoming,
> active community rather than seemingly a group of scattered people
> developing in Cocoons and enabling me to make bad wordplay (such is the
> price). To that end, an agreed upon forum would be ideal.
> > The cocoon community will be delighted at some good documentation.
> > Talking about community I fear such as an active community is to be
> > reestablished, so I think we'd better provide some sweet stuff.
> >
> > What would Reinhard think of starting with as a table of contents?
> > I will be glad to write some documentation as well. I have some goose
> > feathers available after Christmas, when I will be through the
> > experience of creating a first
> > How about you?
> > Jos
> >
> >
> > On Mon, 2009-11-30 at 08:07 -0500, Matt Whipple wrote:
> >
> >> I'm a recent transplant to Cocoon (and Java), in particular because
> >> Cocoon 3 appears as though it is/will be closely in line with my own
> >> perspective on web application development. I'm interested in
> >> contributing to the development of the framework itself, but likely
> >> won't be able to produce anything remotely useful for a couple months
> >> as I familiarize myself with all of the related technologies.
> >>
> >> I've just read some of the attacks on the poor documentation of the
> >> project and the resulting difficult entry for those unfamiliar. This
> >> is, of course, easily confirmed by the combination of woefully out of
> >> date references and dead links on the Web site (i.e. to the Daisy
> >> site). As I am (obviously) hopeful to see Cocoon succeed, I certainly
> >> don't want it to become mired in isolation like so many good projects.
> >>
> >> As such I'd like to try to contribute some documentation. Is there any
> >> idea among the community as to where documentation should end up, or
> >> should I just create a new site? Also, I'd lean towards focusing on
> >> Cocoon 3, as having documentation in place for a new release would
> >> likely have larger impact than attaching possibly overdue docs to an
> >> older, in the process of being superseded one. This would be premature
> >> if there's no foreseeable beta....
> >>
> >>
> >
> >
> >
>
>
Re: Cocoon documentation
Posted by Reinhard Pötz <re...@apache.org>.
Jos Snellings wrote:
> What editor do you use?.
> (I mostly use XMLMind)
yes, either XMLMind or I use use a schema-aware editor.
--
Reinhard Pötz Managing Director, {Indoqa} GmbH
http://www.indoqa.com/en/people/reinhard.poetz/
Member of the Apache Software Foundation
Apache Cocoon Committer, PMC member reinhard@apache.org
________________________________________________________________________
Re: Cocoon documentation
Posted by Jos Snellings <Jo...@pandora.be>.
What editor do you use?.
(I mostly use XMLMind)
On Fri, 2009-12-04 at 12:09 +0100, Reinhard Pötz wrote:
> Jos Snellings wrote:
> > Currently there is an initialisation problem.
> > Anyway, Reinhard, you had a great table of contents. That is a good way
> > to get started: what nodes are missing? That way, we may fill in the
> > gaps, whilst trying our best to preserve unity of presentation & writing
> > style
> > All docbook, I guess?
>
> Yes, cocoon-docs is based on docbook and a Maven 2 docbook plugin that
> creates html and pdf docs:
>
> See
> http://svn.apache.org/repos/asf/cocoon/cocoon3/trunk/cocoon-docs/src/docbkx/reference/
>
> You can generate the documentation yourself by invoking 'mvn site' from
> the base directory of the cocoon-docs module.
>
Re: Cocoon documentation
Posted by Reinhard Pötz <re...@apache.org>.
Thorsten Scherler wrote:
> On Fri, 2009-12-04 at 12:09 +0100, Reinhard Pötz wrote:
> ...
>> See
>> http://svn.apache.org/repos/asf/cocoon/cocoon3/trunk/cocoon-docs/src/docbkx/reference/
>>
>> You can generate the documentation yourself by invoking 'mvn site' from
>> the base directory of the cocoon-docs module.
>
> I tried that but I get:
> ...
> [INFO] Unable to find resource
> 'org.apache.cocoon:cocoon-thien-maven-site-skin:jar:1.0.0-SNAPSHOT' in
> repository apache.snapshots
> (http://people.apache.org/repo/m2-snapshot-repository)
> [INFO]
> ------------------------------------------------------------------------
> [ERROR] BUILD FAILURE
> [INFO]
> ------------------------------------------------------------------------
> [INFO] The skin does not exist: Unable to download the artifact from any
> repository
>
> How can I fix this?
Cocoon 2.2 trunk contains the cocoon-thien-maven-site-skin
(http://svn.apache.org/repos/asf/cocoon/trunk/site/cocoon-thien-maven-site-skin/pom.xml).
Either your build (mvn install) the complete Cocoon 2.2 trunk or you
only build (mvn install) the parent POM and the site skin.
I will also release the site skin so that it is available at the central
Maven 2 repo.
--
Reinhard Pötz Managing Director, {Indoqa} GmbH
http://www.indoqa.com/en/people/reinhard.poetz/
Member of the Apache Software Foundation
Apache Cocoon Committer, PMC member reinhard@apache.org
________________________________________________________________________
Re: Cocoon documentation
Posted by Thorsten Scherler <th...@juntadeandalucia.es>.
On Fri, 2009-12-04 at 12:09 +0100, Reinhard Pötz wrote:
...
> See
> http://svn.apache.org/repos/asf/cocoon/cocoon3/trunk/cocoon-docs/src/docbkx/reference/
>
> You can generate the documentation yourself by invoking 'mvn site' from
> the base directory of the cocoon-docs module.
I tried that but I get:
...
[INFO] Unable to find resource
'org.apache.cocoon:cocoon-thien-maven-site-skin:jar:1.0.0-SNAPSHOT' in
repository apache.snapshots
(http://people.apache.org/repo/m2-snapshot-repository)
[INFO]
------------------------------------------------------------------------
[ERROR] BUILD FAILURE
[INFO]
------------------------------------------------------------------------
[INFO] The skin does not exist: Unable to download the artifact from any
repository
How can I fix this?
salu2
--
Thorsten Scherler <thorsten.at.apache.org>
Open Source Java <consulting, training and solutions>
Sociedad Andaluza para el Desarrollo de la Sociedad
de la Información, S.A.U. (SADESI)
Re: Cocoon documentation
Posted by Reinhard Pötz <re...@apache.org>.
Jos Snellings wrote:
> Currently there is an initialisation problem.
> Anyway, Reinhard, you had a great table of contents. That is a good way
> to get started: what nodes are missing? That way, we may fill in the
> gaps, whilst trying our best to preserve unity of presentation & writing
> style
> All docbook, I guess?
Yes, cocoon-docs is based on docbook and a Maven 2 docbook plugin that
creates html and pdf docs:
See
http://svn.apache.org/repos/asf/cocoon/cocoon3/trunk/cocoon-docs/src/docbkx/reference/
You can generate the documentation yourself by invoking 'mvn site' from
the base directory of the cocoon-docs module.
--
Reinhard Pötz Managing Director, {Indoqa} GmbH
http://www.indoqa.com/en/people/reinhard.poetz/
Member of the Apache Software Foundation
Apache Cocoon Committer, PMC member reinhard@apache.org
________________________________________________________________________
Re: Cocoon documentation
Posted by Jos Snellings <Jo...@pandora.be>.
Currently there is an initialisation problem.
Anyway, Reinhard, you had a great table of contents. That is a good way
to get started: what nodes are missing? That way, we may fill in the
gaps, whilst trying our best to preserve unity of presentation & writing
style
All docbook, I guess?
Jos
On Fri, 2009-12-04 at 10:15 +0100, Reinhard Pötz wrote:
> Matt Whipple wrote:
> > Reinhard Pötz wrote:
> >> Matt Whipple wrote:
> >>
> >>> Jos Snellings wrote:
> >>>
> >>>> The documentation of cocoon-3 can be checked out as:
> >>>> svn co http://svn.apache.org/repos/asf/cocoon/cocoon3/trunk/cocoon-docs\
> >>>>
> >>>>
> >>> I stumbled upon the HTML deliverable of that on
> >>> http://people.apache.org/~reinhard/c3-ref/html/ after sending my email.
> >>> I'd think it would be best if the official documentation focused on
> >>> being primarily a comprehensive reference with a quick bootstrap guide.
> >>> A community documentation site could then supplement that with all the
> >>> typical tutorials/how-to's and tips & tricks which gets the reader where
> >>> he wants to be with a straightforward, minimalist approach which then
> >>> references the official docs and other more enlightening sources.
> >>> Regular articles/blog entries could then highlight the activity in the
> >>> community, and the possibilities of various Cocoon components could be
> >>> showcased. Guides to all of the overlapping processes which can be
> >>> [easily] extrapolated from existing material can be given a home so that
> >>> a potential new developer with a specific need is provided with an
> >>> apparent foot in the door. Basically a site which presents a welcoming,
> >>> active community rather than seemingly a group of scattered people
> >>> developing in Cocoons and enabling me to make bad wordplay (such is the
> >>> price). To that end, an agreed upon forum would be ideal.
> >>>
> >> Agreed. When I started to write the C3 documentation, I had the Spring
> >> reference documentation in mind. I think it's one of the best examples
> >> because it focuses on describing the technology and the concepts.
> >>
> >> As a forum for everything beyond reference docs we could either use
> >> Daisy or the Apache Wiki. (http://wiki.apache.org/cocoon)
> >>
> >>
> > My thought would be Daisy (cocoondev.org?) so the site itself can be
> > Cocoon powered and then the wiki can remain legacy docs.
>
> The Cocoon project runs its own Daisy instance at
> http://cocoon.zones.apache.org/daisy/
>
> We could setup a Cocoon 3 wiki site there.
>
Re: Cocoon documentation
Posted by Reinhard Pötz <re...@apache.org>.
Matt Whipple wrote:
> Reinhard Pötz wrote:
>> Matt Whipple wrote:
>>
>>> Jos Snellings wrote:
>>>
>>>> The documentation of cocoon-3 can be checked out as:
>>>> svn co http://svn.apache.org/repos/asf/cocoon/cocoon3/trunk/cocoon-docs\
>>>>
>>>>
>>> I stumbled upon the HTML deliverable of that on
>>> http://people.apache.org/~reinhard/c3-ref/html/ after sending my email.
>>> I'd think it would be best if the official documentation focused on
>>> being primarily a comprehensive reference with a quick bootstrap guide.
>>> A community documentation site could then supplement that with all the
>>> typical tutorials/how-to's and tips & tricks which gets the reader where
>>> he wants to be with a straightforward, minimalist approach which then
>>> references the official docs and other more enlightening sources.
>>> Regular articles/blog entries could then highlight the activity in the
>>> community, and the possibilities of various Cocoon components could be
>>> showcased. Guides to all of the overlapping processes which can be
>>> [easily] extrapolated from existing material can be given a home so that
>>> a potential new developer with a specific need is provided with an
>>> apparent foot in the door. Basically a site which presents a welcoming,
>>> active community rather than seemingly a group of scattered people
>>> developing in Cocoons and enabling me to make bad wordplay (such is the
>>> price). To that end, an agreed upon forum would be ideal.
>>>
>> Agreed. When I started to write the C3 documentation, I had the Spring
>> reference documentation in mind. I think it's one of the best examples
>> because it focuses on describing the technology and the concepts.
>>
>> As a forum for everything beyond reference docs we could either use
>> Daisy or the Apache Wiki. (http://wiki.apache.org/cocoon)
>>
>>
> My thought would be Daisy (cocoondev.org?) so the site itself can be
> Cocoon powered and then the wiki can remain legacy docs.
The Cocoon project runs its own Daisy instance at
http://cocoon.zones.apache.org/daisy/
We could setup a Cocoon 3 wiki site there.
--
Reinhard Pötz Managing Director, {Indoqa} GmbH
http://www.indoqa.com/en/people/reinhard.poetz/
Member of the Apache Software Foundation
Apache Cocoon Committer, PMC member reinhard@apache.org
________________________________________________________________________
Re: Cocoon documentation
Posted by Matt Whipple <ma...@mattwhipple.com>.
Reinhard Pötz wrote:
> Matt Whipple wrote:
>
>> Jos Snellings wrote:
>>
>>> The documentation of cocoon-3 can be checked out as:
>>> svn co http://svn.apache.org/repos/asf/cocoon/cocoon3/trunk/cocoon-docs\
>>>
>>>
>> I stumbled upon the HTML deliverable of that on
>> http://people.apache.org/~reinhard/c3-ref/html/ after sending my email.
>> I'd think it would be best if the official documentation focused on
>> being primarily a comprehensive reference with a quick bootstrap guide.
>> A community documentation site could then supplement that with all the
>> typical tutorials/how-to's and tips & tricks which gets the reader where
>> he wants to be with a straightforward, minimalist approach which then
>> references the official docs and other more enlightening sources.
>> Regular articles/blog entries could then highlight the activity in the
>> community, and the possibilities of various Cocoon components could be
>> showcased. Guides to all of the overlapping processes which can be
>> [easily] extrapolated from existing material can be given a home so that
>> a potential new developer with a specific need is provided with an
>> apparent foot in the door. Basically a site which presents a welcoming,
>> active community rather than seemingly a group of scattered people
>> developing in Cocoons and enabling me to make bad wordplay (such is the
>> price). To that end, an agreed upon forum would be ideal.
>>
>
> Agreed. When I started to write the C3 documentation, I had the Spring
> reference documentation in mind. I think it's one of the best examples
> because it focuses on describing the technology and the concepts.
>
> As a forum for everything beyond reference docs we could either use
> Daisy or the Apache Wiki. (http://wiki.apache.org/cocoon)
>
>
My thought would be Daisy (cocoondev.org?) so the site itself can be
Cocoon powered and then the wiki can remain legacy docs.
Re: Cocoon documentation
Posted by Reinhard Pötz <re...@apache.org>.
Matt Whipple wrote:
> Jos Snellings wrote:
>> The documentation of cocoon-3 can be checked out as:
>> svn co http://svn.apache.org/repos/asf/cocoon/cocoon3/trunk/cocoon-docs\
>>
> I stumbled upon the HTML deliverable of that on
> http://people.apache.org/~reinhard/c3-ref/html/ after sending my email.
> I'd think it would be best if the official documentation focused on
> being primarily a comprehensive reference with a quick bootstrap guide.
> A community documentation site could then supplement that with all the
> typical tutorials/how-to's and tips & tricks which gets the reader where
> he wants to be with a straightforward, minimalist approach which then
> references the official docs and other more enlightening sources.
> Regular articles/blog entries could then highlight the activity in the
> community, and the possibilities of various Cocoon components could be
> showcased. Guides to all of the overlapping processes which can be
> [easily] extrapolated from existing material can be given a home so that
> a potential new developer with a specific need is provided with an
> apparent foot in the door. Basically a site which presents a welcoming,
> active community rather than seemingly a group of scattered people
> developing in Cocoons and enabling me to make bad wordplay (such is the
> price). To that end, an agreed upon forum would be ideal.
Agreed. When I started to write the C3 documentation, I had the Spring
reference documentation in mind. I think it's one of the best examples
because it focuses on describing the technology and the concepts.
As a forum for everything beyond reference docs we could either use
Daisy or the Apache Wiki. (http://wiki.apache.org/cocoon)
--
Reinhard Pötz Managing Director, {Indoqa} GmbH
http://www.indoqa.com/en/people/reinhard.poetz/
Member of the Apache Software Foundation
Apache Cocoon Committer, PMC member reinhard@apache.org
________________________________________________________________________
Re: Cocoon documentation
Posted by Matt Whipple <ma...@mattwhipple.com>.
Jos Snellings wrote:
> The documentation of cocoon-3 can be checked out as:
> svn co http://svn.apache.org/repos/asf/cocoon/cocoon3/trunk/cocoon-docs\
>
I stumbled upon the HTML deliverable of that on
http://people.apache.org/~reinhard/c3-ref/html/ after sending my email.
I'd think it would be best if the official documentation focused on
being primarily a comprehensive reference with a quick bootstrap guide.
A community documentation site could then supplement that with all the
typical tutorials/how-to's and tips & tricks which gets the reader where
he wants to be with a straightforward, minimalist approach which then
references the official docs and other more enlightening sources.
Regular articles/blog entries could then highlight the activity in the
community, and the possibilities of various Cocoon components could be
showcased. Guides to all of the overlapping processes which can be
[easily] extrapolated from existing material can be given a home so that
a potential new developer with a specific need is provided with an
apparent foot in the door. Basically a site which presents a welcoming,
active community rather than seemingly a group of scattered people
developing in Cocoons and enabling me to make bad wordplay (such is the
price). To that end, an agreed upon forum would be ideal.
> The cocoon community will be delighted at some good documentation.
> Talking about community I fear such as an active community is to be
> reestablished, so I think we'd better provide some sweet stuff.
>
> What would Reinhard think of starting with as a table of contents?
> I will be glad to write some documentation as well. I have some goose
> feathers available after Christmas, when I will be through the
> experience of creating a first
> How about you?
> Jos
>
>
> On Mon, 2009-11-30 at 08:07 -0500, Matt Whipple wrote:
>
>> I'm a recent transplant to Cocoon (and Java), in particular because
>> Cocoon 3 appears as though it is/will be closely in line with my own
>> perspective on web application development. I'm interested in
>> contributing to the development of the framework itself, but likely
>> won't be able to produce anything remotely useful for a couple months
>> as I familiarize myself with all of the related technologies.
>>
>> I've just read some of the attacks on the poor documentation of the
>> project and the resulting difficult entry for those unfamiliar. This
>> is, of course, easily confirmed by the combination of woefully out of
>> date references and dead links on the Web site (i.e. to the Daisy
>> site). As I am (obviously) hopeful to see Cocoon succeed, I certainly
>> don't want it to become mired in isolation like so many good projects.
>>
>> As such I'd like to try to contribute some documentation. Is there any
>> idea among the community as to where documentation should end up, or
>> should I just create a new site? Also, I'd lean towards focusing on
>> Cocoon 3, as having documentation in place for a new release would
>> likely have larger impact than attaching possibly overdue docs to an
>> older, in the process of being superseded one. This would be premature
>> if there's no foreseeable beta....
>>
>>
>
>
>
Re: Cocoon documentation
Posted by Jos Snellings <Jo...@pandora.be>.
The documentation of cocoon-3 can be checked out as:
svn co http://svn.apache.org/repos/asf/cocoon/cocoon3/trunk/cocoon-docs
The cocoon community will be delighted at some good documentation.
Talking about community I fear such as an active community is to be
reestablished, so I think we'd better provide some sweet stuff.
What would Reinhard think of starting with as a table of contents?
I will be glad to write some documentation as well. I have some goose
feathers available after Christmas, when I will be through the
experience of creating a first app.
How about you?
Jos
On Mon, 2009-11-30 at 08:07 -0500, Matt Whipple wrote:
> I'm a recent transplant to Cocoon (and Java), in particular because
> Cocoon 3 appears as though it is/will be closely in line with my own
> perspective on web application development. I'm interested in
> contributing to the development of the framework itself, but likely
> won't be able to produce anything remotely useful for a couple months
> as I familiarize myself with all of the related technologies.
>
> I've just read some of the attacks on the poor documentation of the
> project and the resulting difficult entry for those unfamiliar. This
> is, of course, easily confirmed by the combination of woefully out of
> date references and dead links on the Web site (i.e. to the Daisy
> site). As I am (obviously) hopeful to see Cocoon succeed, I certainly
> don't want it to become mired in isolation like so many good projects.
>
> As such I'd like to try to contribute some documentation. Is there any
> idea among the community as to where documentation should end up, or
> should I just create a new site? Also, I'd lean towards focusing on
> Cocoon 3, as having documentation in place for a new release would
> likely have larger impact than attaching possibly overdue docs to an
> older, in the process of being superseded one. This would be premature
> if there's no foreseeable beta....
>