Fwd: Apache CXF tooling usage definitions

[Eric Johnson <er...@apache.org>]

I think Robert's idea is solid overall. The command line tools should
have good help text and the Apache hosted docs should be presented in
a uniform manner.

However, we cannot ask outside entities to conform to our standards.
Corporate tech writing departments all have their own sets of
standards for how information is presented. We *may* want to use the
FuseSource layout as a template, but IMHO the CXF community should
pick the standard that is the best for the community docs.

I can take a poke around the tool specs and see what text needs to be
added/updated.



---------- Forwarded message ----------
From: Glen Mazza <gl...@gmail.com>
Date: Thu, Nov 11, 2010 at 10:30 AM
Subject: Re: Apache CXF tooling usage definitions
To: users@cxf.apache.org




Robert Liguori wrote:
>
> Note that I personally don't have time to contribute to this, but I do
> think
> that refined, synchronized and more accurate usage definitions would bring
> enhanced 'polished' value to the product.
>

Several of your suggestions Robert would seem better suited for the CXF-Dev
rather than the CXF-User's list.  For any project, not just CXF, many ideas
look excellent at first glance but for various reasons are known not to be
such a great idea by developers and close observers who have spent years
with the project.  However unfair given all your work on the documentation,
heavy usage of CXF-Users over CXF-Dev can give the impression that you
realize that a lot of your ideas hold less and less water the more
experienced one is with the project and that you are using the User
community to unduly push sweet-looking-on-the-surface changes that perhaps
should not be made.

One should also analyze the opportunity cost of making the command line
options looking the same as the GNU conventions compared to adding
additional functionality to CXF, a similar issue to your earlier desire to
have the CXF website be reformatted to look like Camel, ServiceMix, and
ActiveMQ's.  Another factor is that volunteer developers need to work on
tasks that further themselves first and busywork (or "polishing") rarely
accomplishes that.  For open source to be successful, a volunteer developer
should always be *stronger* as a result of volunteering on an open source
project, not weaker.

But, also, as for the issue of time you mention, this brings up an earlier
concern I had about the expansive "thank you" page you recently made
(http://cxf.apache.org/special-thanks.html), in which you list and explain
every Apache and other project that CXF imports, as well as (IMO)
erroneously list Apache-wide helpers like Atlassian that should be thanked
at an Apache-level and not individually within every project.  No question,
it looks very nice and professional now, but who's going to be maintaining
this?  It's like you're giving us a new puppy as a present.  This page is
not going to be looking very nice in several months once it falls out of
date, links get old, etc.  It's not necessary for an Apache project to have
to individually thank every other Apache project it incorporates.  The
source of record for determining the dependencies used by CXF is always
going to be its POM files or the lib folder of its distribution, not a
website page.

So as you enhance the CXF documentation, please be sure that you're not
giving CXF "puppies as presents", things that look cute but are of
relatively limited benefit and need a lot of maintenance afterwards to
remain cute.

Thanks,
Glen

--
View this message in context:
http://cxf.547215.n5.nabble.com/Apache-CXF-tooling-usage-definitions-tp3253466p3260484.html
Sent from the cxf-user mailing list archive at Nabble.com.