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 <glen.ma...@gmail.com> Date: Thu, Nov 11, 2010 at 10:30 AM Subject: Re: Apache CXF tooling usage definitions To: us...@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.