You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@cocoon.apache.org by Mark Leicester <ma...@efurbishment.com> on 2005/06/03 15:42:53 UTC
[Docs] A proposed revision, four weeks for Cocoon, and a smattering of Julie Andrews
Hi everyone,
Starting at the very beginning... I am reviewing the introduction on
the Cocoon home page: http://cocoon.apache.org/ (The "Apache Cocoon"
section). I've added mention of flow, templating and the forms
framework, and tried to increase the emphasis on Cocoon's suitability
for web applications (not just publishing). Possibly contentiously,
I've taken out the references to lego(TM) and glue. What do you think
of:
+----------------------------------------------------+
What is Apache Cocoon?
Apache Cocoon is an MVC web application framework uniquely suited to
XML publishing.
Apache Cocoon is founded on the principle of separation of concerns.
Cocoon's Avalon-based component architecture makes it easy to create
web applications from reusable components. You use the Cocoon Sitemap
to assemble components into pipelines. Pipelines react to client
requests, generating information from a source, transforming it, before
serializing it back to the client in the desired format. This
separation of concerns between generation, transformation and
serialization, allows the same source to be served up to your browser,
cellular phone or printer, or to be consumed by your web service.
In addition to this mature publishing framework, Apache Cocoon offers
features and frameworks to help you build full-featured web
applications. Cocoon Flow offers continuation-based scripting for your
application business logic. Cocoon Templates offer dynamic XML
generation. The Cocoon Forms framework greatly simplifies client
interaction with a growing library of user interface widgets for your
web application forms.
+----------------------------------------------------+
I've embedded links to wikipedia definitions for MVC and SoC, visible
at http://www.planetcocoon.com/node/2155.
My company will pay me to do another four weeks of full time work
reviewing Cocoon documentation (worth about £6000 I guess - a very good
place to start: that's the dough taken care of). My work will include:
- Patches to existing documents.
- Reorganisation of existing documents.
- Revisions of wiki documents.
- New documents.
In terms of semi-supported, semi-official documentation work I am aware
of Helma's efforts at http://cocoondev.org/handbook, Ray was
contributing something too, and obviously I am aware of the work
Sébastien and Me are doing at http://www.planetcocoon.com. At the
moment there seems only sporadic work on the wiki, see
http://wiki.apache.org/cocoon/RecentChanges. Who else is writing
content? Where? How shall we divide up the work?
If you've followed me so Far, then I have another question. What is the
best way to have my work reviewed by the community? To test my
understanding of the current process: for each revision, I would do one
of the following: make a change in the wiki (are these actively
reviewed?); send a patch to bugzilla (it'll be a lot of patches; how do
I submit reorganisations?); or as with the above, start a discussion on
the dev list (I believe the docs list is for change notifications
only?).
A less time consuming alternative for me would be to Sew it all
together at Planet Cocoon, as it is already set up with infrastructure
for anyone wishing to join in, tools for workflow, categorisation,
document hierarchy management etc. If I were to take that approach,
then my work would be continuously visible. Naturally, all my work will
be donated back to Cocoon. And then it'll be time for a nice cuppa.
Which brings us back to... What do others think?
Regards,
Mark
P.S. this took nearly all morning to write. D'oh!
Re: [Docs] A proposed revision, four weeks for Cocoon, and a smattering of Julie Andrews
Posted by Sebastien Arbogast <se...@gmail.com>.
> I spent last weekend going over Cocoon's documentation, various
> threads concerning it and proposed TOCs. I came away with the feeling
> that Cocoon's documentation is written by experienced Cocoon
> developers for experienced Cocoon developers. The only thing Cocoon's
> documentation should assume is that a user is familiar with XML and
> XSLT. If they want to use flow the documentation needs to assume that
> they have some familiarity with javascript and/or Java. Its similar
> for each aspect of Cocoon. Assume only enough to go forward with out
> having to explain things outside of Cocoon.
Obviously we share exactly the same concerns. I don't know if you had
a look at my documentation workflow proposal
(http://www.planetcocoon.com/node/2079) but as you'll see, everything
is made to put readers needs and assumptions about their knowledge at
the center of our documentation writing process.
And I totally agree with you : current documentation is mainly written
by developers for other developers and that's precisely one of the
main reasons why we started our initiative on Planet Cocoon, to create
a real *user* documentation writing platform.
> I have an email that I have been working on since Monday with an
> outline of how I was planing to proceed with writing new
> documentation. Key aspects are that we need to have separate
> documentation for users and developers and that the user
> documentation needs to assume as little as possible about the users
> experience. Hopefully, I will edit down to a few paragraphs and send
> it this weekend.
I'm looking forward to hear your ideas. Maybe it could be the occasion
to join our efforts on Planet Cocoon. That's how I joined Mark in this
initiative, you could join us.
> In the meantime you might want to consider targeting your
> documentation for the most junior and least skilled website developer
> in your company. Better yet, a 1st year student.
Once more we'll even do better than that : we are going to setup a
documentation request mechanism so that people can give details about
what they want to know AND what they already know. That way we'll have
an objective view about what we can assume or not when writing
documentation, and eventually make Cocoon more accessible.
> I mean all this in the most constructive way. Hopefully we will be
> able to collaborate over the next 4 weeks and get a good start on
> rewriting these docs.
That would be great !
Cheers
--
Sebastien ARBOGAST
Re: [Docs] A proposed revision, four weeks for Cocoon, and a smattering of Julie Andrews
Posted by Glen Ezkovich <gl...@hard-bop.com>.
Mark,
On Jun 4, 2005, at 12:05 AM, Mark Leicester wrote:
> Hello Glen,
>
> Thanks for your comments! They are indeed constructive, and you are
> right to raise this issue. Who are we writing for? In simplistic
> terms I imagine two groups: fairly-technical and not-so-technical.
> My solution has been to create one site, http://
> www.spreadcocoon.com, for the not-so-technical market, and another,
> http://www.planetcocoon.com, for the fairly-technical market.
> Spread Cocoon is modelled on http://spreadfirefox.com. It's for
> people who want to know about Cocoon, want to know how it can help
> them, want to hear success stories, see example sites, know about
> Cocoon events, and generally buy badges, posters, stickers and T-
> shirts. On the other hand, Planet Cocoon is a rich developer
> community site where technical people can find the nuts and bolts,
> and get on with being creative. Firefox has similarly separated
> sites, and I believe the same two-pronged approach may work for
> Cocoon.
We are talking about two different things here. An evangelical site
is not the same as a novice site. When we talk about Cocoon users we
are still talking about developers. This most certainly isn't the
case with Firefox users. What I see as the problem, is that the
current documentation assumes a familiarity with both the theories
that led to the development of Cocoon and to some extent Cocoon
itself. (you can find the explanations, but then you get taken off
the path which you were previously following [1]) Someone new to web
development would have a hard time understanding the documentation.
Even experienced developers who were working within a different
framework would have some difficulty in understanding the usefulness
and purpose of Cocoon and some of the various pipeline components.
Its been repeated in several threads concerning documentation and
marketing that Cocoon appears as some huge scary beast. While its
true that the Cocoon distribution has many components and multiple
ways of accomplishing similar tasks, even the most complex pipeline
is pretty simple when compared to a JSP that performs the same tasks.
The documentation should show how simple its to gather data from
various sources and present it to users (human and computer) in
multiple yet consistent ways.
In order to convince developers that Cocoon is both simple and
powerful the documentation needs to consider both the novice and the
experienced developer. That means that explanatory text needs to
assume only minimum knowledge of web development technologies and
theories employed by Cocoon. In order to be accessible to novices
simple examples need to be given. In order to be of value to
experienced developers use cases need to be presented and realistic
examples which solve the problem should be provided. Along with all
of this the documentation needs to also serve as a reference so that
a developer can quickly and easily find the information they need.
That said, there is room for other types of documentation. i.e.
tutorials, recipes, etc. that target various levels of skill. The
main point is that when a user, novice or expert, looks in the main
set of documentation, they find something that at least explains and
demonstrates the aspect of Cocoon in which they are interested, in
such a way that both are satisfied. The one thing I hate is a trivial
example that does not scale as the problem gets slightly more
complex. What I used to hate was an example that was more complex
then I could understand.
>
> This text is targeted at Planet Cocoon: experienced developers,
> wanting to know more, perhaps weighing up Cocoon as a possible
> solution alongside other web application frameworks. Let's get this
> text right for developers. We can tailor it further for different
> types of developers, like "Click here if you want to compare Cocoon
> with Struts", "Click here if you want to compare Cocoon with .NET",
> "Click here if you are a 1st year student who wants to change the
> world".
Thats fine. It will allow them to compare Cocoon to other frameworks
or become more involved with the Cocoon community. What it won't do
is explain the concepts.
>
> For the equivalent high-level paragraphs on Spread Cocoon, I can
> imagine wholly different language oriented to the non-technical
> public. Let's develop a version of this text for the general,
> thrill-seeking, public.
OK, do you know of anyone who accesses a cocoon driven site and who
is not a developer and who cares that the site is built on Cocoon?
Anyone who is going to access a site devoted to Cocoon, is most
likely a developer.
>
> Please remember that neither of the efforts I am discussing are in
> any way official, or representative of the views of the Cocoon PMC.
I remember. I'm not that old that my short term memory is shot.
(close but not yet) :-)
>
> You are quite right: it's about knowing your audience. I am looking
> forward to hearing what you and others have to say!
I'm not going to say as much as I planed. I'm working on keeping my
mouth shut. Seriously, I want to get started on improving the
documentation. I'll be sending an email outlining the direction in
which I'll be heading. Unfortunately, I won't be getting paid to work
on this so the time frame is a bit of a question.
[1] http://cocoon.apache.org/2.1/userdocs/index.html takes you to
http://cocoon.apache.org/2.1/userdocs/concepts/index.html from which
you must go back to user documentation to continue.
Glen Ezkovich
HardBop Consulting
glen at hard-bop.com
A Proverb for Paranoids:
"If they can get you asking the wrong questions, they don't have to
worry about answers."
- Thomas Pynchon Gravity's Rainbow
Re: [Docs] A proposed revision, four weeks for Cocoon, and a smattering of Julie Andrews
Posted by Mark Leicester <ma...@efurbishment.com>.
Hello Glen,
Thanks for your comments! They are indeed constructive, and you are
right to raise this issue. Who are we writing for? In simplistic terms
I imagine two groups: fairly-technical and not-so-technical. My
solution has been to create one site, http://www.spreadcocoon.com, for
the not-so-technical market, and another, http://www.planetcocoon.com,
for the fairly-technical market. Spread Cocoon is modelled on
http://spreadfirefox.com. It's for people who want to know about
Cocoon, want to know how it can help them, want to hear success
stories, see example sites, know about Cocoon events, and generally buy
badges, posters, stickers and T-shirts. On the other hand, Planet
Cocoon is a rich developer community site where technical people can
find the nuts and bolts, and get on with being creative. Firefox has
similarly separated sites, and I believe the same two-pronged approach
may work for Cocoon.
This text is targeted at Planet Cocoon: experienced developers, wanting
to know more, perhaps weighing up Cocoon as a possible solution
alongside other web application frameworks. Let's get this text right
for developers. We can tailor it further for different types of
developers, like "Click here if you want to compare Cocoon with
Struts", "Click here if you want to compare Cocoon with .NET", "Click
here if you are a 1st year student who wants to change the world".
For the equivalent high-level paragraphs on Spread Cocoon, I can
imagine wholly different language oriented to the non-technical public.
Let's develop a version of this text for the general, thrill-seeking,
public.
Please remember that neither of the efforts I am discussing are in any
way official, or representative of the views of the Cocoon PMC.
You are quite right: it's about knowing your audience. I am looking
forward to hearing what you and others have to say!
Regards,
Mark
> Mark, I applaud your efforts to improve Cocoon's documentation and I
> am thankful for your company footing the bill. However, I think what
> you have written above just continues the existing problem with a
> different set of words. The two paragraphs as a whole assume
> familiaraity with the concepts of MVC, separation of concerns, that
> Cocoon has a sitemap and what that is, pipelines, generation,
> transformation and serialization and continuation-based scripting. If
> I were completely unfamiliar with Cocoon, I really still would not
> know what it is other then a web application framework.
>
> I spent last weekend going over Cocoon's documentation, various
> threads concerning it and proposed TOCs. I came away with the feeling
> that Cocoon's documentation is written by experienced Cocoon
> developers for experienced Cocoon developers. The only thing Cocoon's
> documentation should assume is that a user is familiar with XML and
> XSLT. If they want to use flow the documentation needs to assume that
> they have some familiarity with javascript and/or Java. Its similar
> for each aspect of Cocoon. Assume only enough to go forward with out
> having to explain things outside of Cocoon.
>
> I have an email that I have been working on since Monday with an
> outline of how I was planing to proceed with writing new
> documentation. Key aspects are that we need to have separate
> documentation for users and developers and that the user documentation
> needs to assume as little as possible about the users experience.
> Hopefully, I will edit down to a few paragraphs and send it this
> weekend.
>
> In the meantime you might want to consider targeting your
> documentation for the most junior and least skilled website developer
> in your company. Better yet, a 1st year student.
>
> I mean all this in the most constructive way. Hopefully we will be
> able to collaborate over the next 4 weeks and get a good start on
> rewriting these docs.
>
> Glen Ezkovich
> HardBop Consulting
> glen at hard-bop.com
>
>
>
> A Proverb for Paranoids:
> "If they can get you asking the wrong questions, they don't have to
> worry about answers."
> - Thomas Pynchon Gravity's Rainbow
>
Re: [Docs] A proposed revision, four weeks for Cocoon, and a smattering of Julie Andrews
Posted by Glen Ezkovich <ge...@cox.net>.
On Jun 3, 2005, at 8:42 AM, Mark Leicester wrote:
> What is Apache Cocoon?
>
> Apache Cocoon is an MVC web application framework uniquely suited
> to XML publishing.
>
> Apache Cocoon is founded on the principle of separation of
> concerns. Cocoon's Avalon-based component architecture makes it
> easy to create web applications from reusable components. You use
> the Cocoon Sitemap to assemble components into pipelines. Pipelines
> react to client requests, generating information from a source,
> transforming it, before serializing it back to the client in the
> desired format. This separation of concerns between generation,
> transformation and serialization, allows the same source to be
> served up to your browser, cellular phone or printer, or to be
> consumed by your web service.
>
> In addition to this mature publishing framework, Apache Cocoon
> offers features and frameworks to help you build full-featured web
> applications. Cocoon Flow offers continuation-based scripting for
> your application business logic. Cocoon Templates offer dynamic XML
> generation. The Cocoon Forms framework greatly simplifies client
> interaction with a growing library of user interface widgets for
> your web application forms.
Mark, I applaud your efforts to improve Cocoon's documentation and I
am thankful for your company footing the bill. However, I think what
you have written above just continues the existing problem with a
different set of words. The two paragraphs as a whole assume
familiaraity with the concepts of MVC, separation of concerns, that
Cocoon has a sitemap and what that is, pipelines, generation,
transformation and serialization and continuation-based scripting. If
I were completely unfamiliar with Cocoon, I really still would not
know what it is other then a web application framework.
I spent last weekend going over Cocoon's documentation, various
threads concerning it and proposed TOCs. I came away with the feeling
that Cocoon's documentation is written by experienced Cocoon
developers for experienced Cocoon developers. The only thing Cocoon's
documentation should assume is that a user is familiar with XML and
XSLT. If they want to use flow the documentation needs to assume that
they have some familiarity with javascript and/or Java. Its similar
for each aspect of Cocoon. Assume only enough to go forward with out
having to explain things outside of Cocoon.
I have an email that I have been working on since Monday with an
outline of how I was planing to proceed with writing new
documentation. Key aspects are that we need to have separate
documentation for users and developers and that the user
documentation needs to assume as little as possible about the users
experience. Hopefully, I will edit down to a few paragraphs and send
it this weekend.
In the meantime you might want to consider targeting your
documentation for the most junior and least skilled website developer
in your company. Better yet, a 1st year student.
I mean all this in the most constructive way. Hopefully we will be
able to collaborate over the next 4 weeks and get a good start on
rewriting these docs.
Glen Ezkovich
HardBop Consulting
glen at hard-bop.com
A Proverb for Paranoids:
"If they can get you asking the wrong questions, they don't have to
worry about answers."
- Thomas Pynchon Gravity's Rainbow
Re: [Docs] A proposed revision, four weeks for Cocoon, and a smattering
of Julie Andrews
Posted by Nicola Ken Barozzi <ni...@apache.org>.
Reinhard Poetz wrote:
> Upayavira wrote:
>
>> Well, given Steven is working on setting up Daisy right now, I think
>> we might need that. How much change would our SVN repo require to make
>> 0.7 work?
>
> AFAIK our repositories build fine with Forrest 0.7. The person doing the
> conversion of the docs into the format required by Daisy should have a
> look at the project sitemap where he will find some pipelines that
> should be helpful.
If Daisy uses HTML, then it can use Forrest to convert it all using the
plain-dev skin.
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
Re: [Docs] A proposed revision, four weeks for Cocoon, and a smattering
of Julie Andrews
Posted by Reinhard Poetz <re...@apache.org>.
Upayavira wrote:
> Reinhard Poetz wrote:
>
>> Upayavira wrote:
>>
>>> Well, given Steven is working on setting up Daisy right now, I think
>>> we might need that. How much change would our SVN repo require to
>>> make 0.7 work?
>>
>>
>>
>> AFAIK our repositories build fine with Forrest 0.7. The person doing
>> the conversion of the docs into the format required by Daisy should
>> have a look at the project sitemap where he will find some pipelines
>> that should be helpful.
>
>
> Including the 2.1 ones?
sorry, don't know. Maybe David knows this.
--
Reinhard Pötz Independent Consultant, Trainer & (IT)-Coach
{Software Engineering, Open Source, Web Applications, Apache Cocoon}
web(log): http://www.poetz.cc
--------------------------------------------------------------------
___________________________________________________________
Gesendet von Yahoo! Mail - Jetzt mit 1GB Speicher kostenlos - Hier anmelden: http://mail.yahoo.de
Re: [Docs] A proposed revision, four weeks for Cocoon, and a smattering
of Julie Andrews
Posted by Upayavira <uv...@odoko.co.uk>.
Reinhard Poetz wrote:
> Upayavira wrote:
>
>> Well, given Steven is working on setting up Daisy right now, I think
>> we might need that. How much change would our SVN repo require to make
>> 0.7 work?
>
>
> AFAIK our repositories build fine with Forrest 0.7. The person doing the
> conversion of the docs into the format required by Daisy should have a
> look at the project sitemap where he will find some pipelines that
> should be helpful.
Including the 2.1 ones?
Upayavira
Re: [Docs] A proposed revision, four weeks for Cocoon, and a smattering
of Julie Andrews
Posted by Reinhard Poetz <re...@apache.org>.
Upayavira wrote:
> Well, given Steven is working on setting up Daisy right now, I think we
> might need that. How much change would our SVN repo require to make 0.7
> work?
AFAIK our repositories build fine with Forrest 0.7. The person doing the
conversion of the docs into the format required by Daisy should have a look at
the project sitemap where he will find some pipelines that should be helpful.
--
Reinhard Pötz Independent Consultant, Trainer & (IT)-Coach
{Software Engineering, Open Source, Web Applications, Apache Cocoon}
web(log): http://www.poetz.cc
--------------------------------------------------------------------
Re: [Docs] A proposed revision, four weeks for Cocoon, and a smattering
of Julie Andrews
Posted by Upayavira <uv...@odoko.co.uk>.
Ross Gardler wrote:
> Upayavira wrote:
>
>> Ross Gardler wrote:
>>
>>> Reinhard Poetz wrote:
>>>
>>>> Upayavira wrote:
>>>>
>>>>> * This will mean that the end result will be xdocs, not HTML.
>>>>> However,
>>>>> I don't believe converting HTML to xdocs would be hard, and I'd
>>>>> happily knock up a script to do any necessary conversions.
>>>>
>>>>
>>>>
>>>>
>>>>
>>>> actually Forrest already does this
>>>>
>>>
>>> 0.6 does work with HTML, but you have to rename the files to *.ehtml
>>> in order to have them skinned
>>>
>>> Forrest 0.7-dev will work happily with most HTML docs without any
>>> kind of modification (anything it doesn't handle well is an oversight
>>> so we will patch for it).
>>>
>>> What version of Forrest does Cocoon currently work with. It is not a
>>> major step to upgrade to 0.7 if necessary.
>>
>>
>>
>> I believe we're now at 0.6 (ish).
>
>
> OK, 0.7 is in the final stages of development, we are just tidying up
> before the release. If you find the need to upgrade I will offer my
> assistance (you will have to upgrade in order to pull docuements from
> external sources like Daisy as that is part of the new plugin system).
Well, given Steven is working on setting up Daisy right now, I think we
might need that. How much change would our SVN repo require to make 0.7
work?
Regards, Upayavira
Re: [Docs] A proposed revision, four weeks for Cocoon, and a smattering
of Julie Andrews
Posted by Ross Gardler <rg...@apache.org>.
Upayavira wrote:
> Ross Gardler wrote:
>
>> Reinhard Poetz wrote:
>>
>>> Upayavira wrote:
>>>
>>>> * This will mean that the end result will be xdocs, not HTML. However,
>>>> I don't believe converting HTML to xdocs would be hard, and I'd
>>>> happily knock up a script to do any necessary conversions.
>>>
>>>
>>>
>>>
>>> actually Forrest already does this
>>>
>>
>> 0.6 does work with HTML, but you have to rename the files to *.ehtml
>> in order to have them skinned
>>
>> Forrest 0.7-dev will work happily with most HTML docs without any kind
>> of modification (anything it doesn't handle well is an oversight so we
>> will patch for it).
>>
>> What version of Forrest does Cocoon currently work with. It is not a
>> major step to upgrade to 0.7 if necessary.
>
>
> I believe we're now at 0.6 (ish).
OK, 0.7 is in the final stages of development, we are just tidying up
before the release. If you find the need to upgrade I will offer my
assistance (you will have to upgrade in order to pull docuements from
external sources like Daisy as that is part of the new plugin system).
Ross
Re: [Docs] A proposed revision, four weeks for Cocoon, and a smattering
of Julie Andrews
Posted by Upayavira <uv...@odoko.co.uk>.
Ross Gardler wrote:
> Reinhard Poetz wrote:
>
>> Upayavira wrote:
>>
>>> * This will mean that the end result will be xdocs, not HTML. However,
>>> I don't believe converting HTML to xdocs would be hard, and I'd
>>> happily knock up a script to do any necessary conversions.
>>
>>
>>
>> actually Forrest already does this
>>
>
> 0.6 does work with HTML, but you have to rename the files to *.ehtml in
> order to have them skinned
>
> Forrest 0.7-dev will work happily with most HTML docs without any kind
> of modification (anything it doesn't handle well is an oversight so we
> will patch for it).
>
> What version of Forrest does Cocoon currently work with. It is not a
> major step to upgrade to 0.7 if necessary.
I believe we're now at 0.6 (ish).
Upayavira
Re: [Docs] A proposed revision, four weeks for Cocoon, and a smattering
of Julie Andrews
Posted by Ross Gardler <rg...@apache.org>.
Reinhard Poetz wrote:
> Upayavira wrote:
>
>> * This will mean that the end result will be xdocs, not HTML. However,
>> I don't believe converting HTML to xdocs would be hard, and I'd
>> happily knock up a script to do any necessary conversions.
>
>
> actually Forrest already does this
>
0.6 does work with HTML, but you have to rename the files to *.ehtml in
order to have them skinned
Forrest 0.7-dev will work happily with most HTML docs without any kind
of modification (anything it doesn't handle well is an oversight so we
will patch for it).
What version of Forrest does Cocoon currently work with. It is not a
major step to upgrade to 0.7 if necessary.
Ross
Re: [Docs] A proposed revision, four weeks for Cocoon, and a smattering
of Julie Andrews
Posted by Reinhard Poetz <re...@apache.org>.
Upayavira wrote:
> * This will mean that the end result will be xdocs, not HTML. However,
> I don't believe converting HTML to xdocs would be hard, and I'd
> happily knock up a script to do any necessary conversions.
actually Forrest already does this
--
Reinhard Pötz Independent Consultant, Trainer & (IT)-Coach
{Software Engineering, Open Source, Web Applications, Apache Cocoon}
web(log): http://www.poetz.cc
--------------------------------------------------------------------
Re: [Docs] A proposed revision, four weeks for Cocoon, and a smattering
of Julie Andrews
Posted by Upayavira <uv...@odoko.co.uk>.
Mark Leicester wrote:
> Hi everyone,
>
> Starting at the very beginning... I am reviewing the introduction on the
> Cocoon home page: http://cocoon.apache.org/ (The "Apache Cocoon"
> section). I've added mention of flow, templating and the forms
> framework, and tried to increase the emphasis on Cocoon's suitability
> for web applications (not just publishing). Possibly contentiously, I've
> taken out the references to lego(TM) and glue. What do you think of:
>
I've moved that bit to the end, because it seems to come second to me.
> My company will pay me to do another four weeks of full time work
> reviewing Cocoon documentation (worth about £6000 I guess - a very good
> place to start: that's the dough taken care of). My work will include:
> - Patches to existing documents.
> - Reorganisation of existing documents.
> - Revisions of wiki documents.
> - New documents.
Hey, anyone offering time, we'll appreciate it. Time is what the docs
really need, for sure.
> In terms of semi-supported, semi-official documentation work I am aware
> of Helma's efforts at http://cocoondev.org/handbook, Ray was
> contributing something too, and obviously I am aware of the work
> Sébastien and Me are doing at http://www.planetcocoon.com. At the moment
> there seems only sporadic work on the wiki, see
> http://wiki.apache.org/cocoon/RecentChanges. Who else is writing
> content? Where? How shall we divide up the work?
There's also mine and Reinhard's effort to rework the existing docs in
readiness for 2.2.
Some points:
* Myself and Reinhard have been working on converting the docs to 2.2.
We have got a decent framework in place, but we haven't done much
work on actual documentation. Rerunning the 2.1 to 2.2 conversion
process wouldn't be that hard.
* If we want to get anything you do published quickly (i.e. less than
six months), it is going to have to end up in the 2.1.X Cocoon SVN.
* This will mean that the end result will be xdocs, not HTML. However,
I don't believe converting HTML to xdocs would be hard, and I'd
happily knock up a script to do any necessary conversions.
* I'm not that fussed where a document is worked on before it gets in
to SVN, so long as:
(a) it is accessible to a wide range of people who can contribute
(b) change notifications are sent out whenever content is changed
(this is necessary to trigger an otherwise lazy community to
take notice of your work)
(c) it isn't too hard to convert the content across to HTML or xdoc
format.
So, I'd say that the work that is required is to do sort out the
reference documentation, and to extend that with tutorials and
introductory material. What area would you want to be starting with?
> If you've followed me so Far, then I have another question. What is the
> best way to have my work reviewed by the community? To test my
> understanding of the current process: for each revision, I would do one
> of the following: make a change in the wiki (are these actively
> reviewed?); send a patch to bugzilla (it'll be a lot of patches; how do
> I submit reorganisations?); or as with the above, start a discussion on
> the dev list (I believe the docs list is for change notifications only?).
Patches is how content will need to get into SVN, but isn't, as you
suggest, the best way to actually go about the editorial work.
> A less time consuming alternative for me would be to Sew it all together
> at Planet Cocoon, as it is already set up with infrastructure for anyone
> wishing to join in, tools for workflow, categorisation, document
> hierarchy management etc. If I were to take that approach, then my work
> would be continuously visible. Naturally, all my work will be donated
> back to Cocoon. And then it'll be time for a nice cuppa. Which brings us
> back to... What do others think?
Start small, do a page or two at a time, so you can stop at any point
and there's something valuable left. And we can complain and say "no,
that's not what we want" before you've wasted heaps of time.
Other than that, just get on with it :-)
> P.S. this took nearly all morning to write. D'oh!
I can believe it!
> +----------------------------------------------------+
> What is Apache Cocoon?
>
> Apache Cocoon is an MVC web application framework uniquely suited to XML
> publishing.
>
> Apache Cocoon is founded on the principle of separation of concerns.
> Cocoon's Avalon-based component architecture makes it easy to create web
> applications from reusable components. You use the Cocoon Sitemap to
> assemble components into pipelines. Pipelines react to client requests,
> generating information from a source, transforming it, before
> serializing it back to the client in the desired format. This separation
> of concerns between generation, transformation and serialization, allows
> the same source to be served up to your browser, cellular phone or
> printer, or to be consumed by your web service.
>
> In addition to this mature publishing framework, Apache Cocoon offers
> features and frameworks to help you build full-featured web
> applications. Cocoon Flow offers continuation-based scripting for your
> application business logic. Cocoon Templates offer dynamic XML
> generation. The Cocoon Forms framework greatly simplifies client
> interaction with a growing library of user interface widgets for your
> web application forms.
> +----------------------------------------------------+
> I've embedded links to wikipedia definitions for MVC and SoC, visible at
> http://www.planetcocoon.com/node/2155.
To be honest, I'd probably leave this bit until a little later. This is
probably one of the more contentious pieces. Start somewhere simpler! I
can imagine a very long thread about a short, pithy, summary of what
Cocoon is, and I think we would do well to leave that for a week or two.
Does that sound reasonable?
Look forward to seeing what you come up with.
Regards, Upayavira