cxf-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Glen Mazza <glen.ma...@gmail.com>
Subject Concerns about the Camel / CXF documentation
Date Thu, 28 Aug 2008 06:34:25 GMT

Christian,

I have a few concerns about your write up on using Camel as a JMS
alternative with CXF[1]:

1.)  I don't understand why you are duplicating your blog entry on a CXF
confluence page.  Can't you just keep your blog entry up-to-date with your
link to it from our articles[2] page (and perhaps a few sentences on our JMS
page linking to it, for those who miss the articles page)?  Your article
looks nicer on your blog anyway than it does with Confluence formatting.

2.)  The quality of the writing on the Confluence page is not very clean--it
hasn't been spell-checked, capitalization is frequently off ("apache camel"
instead of "Apache Camel"), detracting from the CXF documentation as a
whole, and the tone reads too informally.  Also, you have too many
references to specific developers and regular usage of the first-person
"I"--it is written like a blog entry instead of actual system documentation. 
We really don't have time to be cleaning this documentation up, you need to
proofread more carefully.

I write blog entries and link them to the articles page, and I also update
the CXF system documentation (sometimes linking to a blog entry, either mine
or others).  But the writing styles are different, and the types of things
you include are different.  In particular, you are tying your Confluence
article too much to yourself, but Confluence pages are for any team member
to edit, and are normally written without reference to any particular
author.

3.)  The tone of the documentation would appear to make it a better
candidate on the Camel site rather than the CXF one, for two reasons.  (And
I'm sure James Strachan would be happy to give you a place to write
articles.)  For one thing, the criticisms of the CXF product, as in your
entry paragraphs, is unnatural within CXF documentation.

Quote:  "Configuring JMS in Apache CXF is possible but not really easy or
nice. This article shows how to use Apache Camel to provide a better JMS
Transport for CXF...JMS configuration in Apache CXF is possible but the
configuration is not very flexible and quite error prone. In CXF you have to
configure a JMSConduit or a JMSDestination for each webservice. The
connection between Conduit and the Service proxy is the endpoint name which
looks like "{http://service.test\}HelloWorldPort.jms-conduit". As this name
is never explicitly configured elsewhere it is quite probable that you
misspell the name. If this happens then the JMS Transport just does not
work. There is no good error reporting to show you what you did wrong."

Pointing out the minuses of a software product, such as CXF, is perfectly
acceptable, but not on the CXF's product's page itself--this should with the
Camel project, where you are explaining an alternative.  That's where you
establish the contrast, the criticisms that you're finding with CXF.  While
you can still link to alternative and better solutions from the CXF site
(and even say they're better), the self-criticism part directly within the
system documentation seems strange.

For example, if I want to suggest where Maven is better than Apache Ant for
building software, those technical articles (and legitimate criticisms) go
on the Maven website ("Apache Ant is good for many things, but falls short
in these project-building aspects...), not on the Ant website.  It is
unusual to ask team members to maintain documentation criticizing their
project.  

For the second reason, Camel embeds CXF--not vice-versa; for that reason,
perhaps placement on the Camel site would appear more appropriate, with just
links from CXF.

Regards,
Glen

[1] http://tinyurl.com/57ol4h
[2] http://cwiki.apache.org/confluence/display/CXF/Resources+and+Articles

-- 
View this message in context: http://www.nabble.com/Concerns-about-the-Camel---CXF-documentation-tp19194940p19194940.html
Sent from the cxf-dev mailing list archive at Nabble.com.


Mime
View raw message