cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Steven Noels <>
Subject [Fwd: Marketing Cocoon or: My first, my second and my current impression - request for comments]
Date Mon, 28 Apr 2003 22:52:53 GMT
I'm not implying anything and there's no real new things in it, but I 
felt this should be forwarded here.


-------- Original Message --------
Subject: 	Marketing Cocoon or: My first, my second and my current
impression - request for comments
Date: 	Tue, 29 Apr 2003 00:10:38 +0200
From: 	Torsten Schlabach <>
To: 	<>

Dear List,

having watched the Cocoon project for quite some time (> 1 year) and
having worked with it intensively over the last couple of weeks, I found
it was the right time to take a break and do some check on if I am alone
with findings or if other people agree with me. So I would like to point
out that the following is no blaming anyone for anything but maybe food
for thoughts.

As a backgrounder: I have been building websites probably for 10 years
now, but I never did this for a living. I am not a designer but rather a
programmer / technical and maybe to some extend an editor kind of
person. So since I wrote my very first <html><body><p>Hello
World!</p></body></html> type of page I was often more interested in the
technical architecture than I was necessarily in the content of
websites. Having had some exposure to general management (read:
encounter with people to who computers are next to black magic) I was
always interested in how content would make its way from brains that
create it into some media (i.e. websites) so it was ready for others to
be consumed. This background creates a natural interest in any kind of
“dynamic websites” and “content management systems”.

It might have been about two years ago that I again was asked by someone
to take care of a website which made me get an update on free content
management systems. I experimented with some PHP based solutions, quite
quickly recognizing their limitations when I heared about Cocoon for the
first time. I was pretty much in the situation that is described in the
Cocoon introduction on the website:

[“Everybody talks about XML. XML here, XML there. All application
servers support XML, everybody wants to do B2B using XML, web services
using XML, even databases using XML. Should you care about it?”]

So I decided I cared, got the stuff (it might have been 2.0.x),
installed it and started looking at the samples which kind of impressed
me. But then I wanted to start my own website using Cocoon and ran into
the first problems:

- There is no real “Getting started” guide. At least I did not find it.
In fact until today I have trouble to decide if I would look for the
information I need in the “Users Guide” or in the “Developers Guide”.
While the developers guide appears to me as a number of unrelated topics
that require tons of knowledge of the terminology of other Apache
projects I thought I might want to have a look at the “Users Guide”,
because I waned to use Cocoon to get my job done.

- The Users Guide explains the concepts, but only scratches the surface
on topics that people really better make sure they understand and has
lots of details about things that people don’t need to know upfront (but
might want to dig into later).

- Finally, there are the usually quite promising sections called
“Tutorials” and “How-tos”. Unfortunately they are both kind of a
collection of external links to some unrelated topics and to me they are
in particular order.

So I decided to forget about the written word and turn to the code. I
picked one of the examples (I used that Bicycle job website), make a
copy of it and tried to change this so it would eventually turn into the
website I was looking for. It was when I tried to introduce an
authentication piece from a different example when I knew I knew
nothing. (Not sure if this works in English. In Latin that would be
“Scio me nescire”.)

This was also when I found that it is no fun to write a website with
custom tags in an XML editor and manually built XSL stylesheets to make
them eventually look the way I wanted them to. At that time, Dreamwaver
and similar HTML editors had already been commonplace it the discrepance
between the two approaches was just too big. Finally when I failed to
figure out how to use HTML markup like <b></b> or tables in that
proprietary XML pages from that sample this was when it found Cocoon was
just not for me. So that website got build on PHP.

It was about two months ago (I had worked with XML a lot in other
respects in the meanwhile) when I again was volunteered to take care
about a charity organizations website. We were a team of three: One
designer who contributed the layout, one PR woman who was taking card of
content (and about updating it) and me to worry about technical aspects.
I decided to give Cocoon a second look.

This was for one reason: Given the team structure I wanted to make sure
that the editor(s) can use a standard HTML editor (such as Dreamwaver)
to build their pages, but I wanted to make sure they can neither mess
with the menu structure of the site nor with its design. I was imagining
a setup with two directories on the server: One that had all the files
that were **content** (accessible to the editors) and one that I called
the **framework** providing navigation, stylesheets, meta-tags, titles, etc.

I found that Cocoon had a lot to offer than we could make use of such as
the PDF serializer that would allow us to have membership form
dynamically created with all details of the person joining filled in
(for signing and faxing), sending form content as e-mails in case
visitors of the site requested brochures or the like and finally the
ability to have parts of the site downloadable as a PDF book to go. (We
deal with Afghanistan, where online access is quite limited, so it often
would make sense to our audience to download content and take it with
then or even print it out and distribute physically.)

Having had the idea to use XHTML and therefore being able to use WYSIWYG
editors to create and edit pages, I arrived at my second impression of
Cocoon: It really can do a lot for you.

The overall plan sounding maybe somewhat ambitious it were in fact some
of the most basic things that took me literally full days to make them
work. One of them for example was as simple as this: Imaging you have an
XHTML page that is pretty much the container for your actual content. It
would look like this:



<title>I would have to put a different title in here for each page</title>



This is the main menu:


<li>Item 1</li>

<li>Item 2</li>


<!—this would be the place for the actual content à

<p>This is the footer in each page</p>



I’ve experimented for about a week with content aggregation trying to
split the page into three parts: header / content / footer, used XSL to
replace a custom tag in the page with the actual content (think of this
being a template which means that whatever is included depends on the
actual page requested) until I finally arrived at the concept of
XInclude, the XPath and XPointer syntax and found the cocoon: special
resources and the possibility to access sitemap parameters from places
where I would not have expected this. So the solution was much easier
than I thought. Just nobody told me.

(In fact, this is the theory which is overlayed by the practical fact
that unfortunately there are some things broken in Cocoon that can
really take someone who’s not having pointy brackets for breakfast nuts.
Just let me mention the two bugs:

#17763 (comments from DTD cause invalid XML) – no workaround yet. After
two days of getting desperate I decided to patch my DTDs so they just
did not include any comments any more. This way I learned how to use sed
for the first time.)

#xxxx (I will file that bug tomorrow morning: XPointer is broken) – see
the discussion on this from today on the list. Extracting the body of a
document using /html/body does not work; //html/body/* does. Another
fully lost day – 10 ½ working hours that made me deal with a lot of
Cocoon, Xalan and Xerces internals, but seen from an effort to result
perspective this was not really efficient.

There have been other problems that I had suffered from, but I don’t
remember each and every one. All I remember is quite long working days
and nights that were just too much for the result I got.

I found that I have to attribute this two three issues:

- My lack of rock-solid, current and complete XML knowledge. To be
honest: I know what well-formed means. I had heard about namespaces
before but I never really knew what they are good for and I always
thought the only difference between XHTML and HTML was that tags need to
be in lowercase overlooking issues like &uuml means something entirely
different in HTML than it does in XHTML. Might be my homework to be
done, but what would have helped me would have been some words on what I
should familiarise myself with any why I would need that.

- The lack of actionable, enlightening documentation. All the docs on
the Cocoon website sort of state the obvious but are probably not
written for the perspective of an outsider who needs introduction to the
concepts and targeted results after each piece of documentation. It is
more written to **remind** someone who is already grounded into the
Cocoon community about the most important details.

- The quality of the software. Sorry, but it major elementary features
of XML handling are broken (see above) this does not necessarily help
people evaluating the project to gain trust and recommending building
production sites on Cocoon. Also if porting apps that worked fine in
2.0.4 to the current CVS HEAD leads to nothing but “No Message / No
Details available / java.lang.NullPointerException” this adds to the
impression. Next problem being an improved mail handling which was my
primary reason for upgrading to 2.1 where it took me two days to make
the sample work at all. (Thanks for the help of Christian Haul who
figured that this was an issue with the default configuration that
needed a change.)

Partially it seems as if the problem was that Cocoon of course is
relying on a lot of exterior building blocks such as the Xalan and
Xerces components. But then what about introducing some regression test
mechanisms so that problems of this kind are recognized earlier and can
be reported, maybe with potential workarounds, so it will not be dozens
of people wasting their time again and again with the same bugs. (That
resources could be utilised better somewhere else in the project.)

Finally the website (including the version that is in the CVS) is not
what I would call a showcase for Cocoon itself. What’s missing in my
view is:

- Search

- Download as PDF (to be able to search there or to be able to print and
put it on your desk. Wasn’t that what the whole separation of Content
and Design issue was all about)

- Having the whole site available to WAP browsers on smartphones, not
just the “Hello World” example. This would probably be the single most
attracting demonstration to non-technical people these days to make them
understand what Cocoon is good for.

- Improved FAQs and tutorials. I think a good example is the Jakarta
Struts project in this respect. While it’s not perfect it does a much
better job here in my view.

I’ve been watching this sentence for more than a year now:

[“Come back often...this guide is being updated regularly.”]

It’s from the Cocoon website. (If you don’t know by heart where it
stands: Try to find it without a search facility!) It did not change
since I am watching it. Why don’t we start delivering on that promise?


Steven Noels                  
Outerthought - Open Source, Java & XML Competence Support Center
Read my weblog at  
stevenn at                stevenn at

View raw message