Making the SMX 4 examples clearer

[Aidan Hollinshead <ai...@progress.com>]

Hi,

As a relative newbie to ServiceMix 4, I was going through the examples 
and saw a few things I thought could perhaps be improved, and I'd like 
to help

1. Write a top-level README in the examples directory that lists the 
demos and what they do because it's hard to figure out just from 
directory names where you should start. I'm assuming this would cover 
the examples that are released.

2. Add a bit more explanatory information to the READMEs and a 
consistent format, including an overview of what the demo does (what 
particular feature or pattern it's demonstrating), what parts make up 
the example, and which config files or code are particularly important 
to this example, then the usual instructions on how to build and/or run 
the example. I know some of the examples, for example do have some more 
explanation already on servicemix.apache.org but that only applies to a 
couple.

3. Write READMEs for the examples that weren't in the 4.0.0.0 release 
but are in SVN.

There are some other ideas that are a bit more structural and would thus 
have more side effects. I know some of the examples (bridge, camel & 
cxf-wsdl-first) are carried over from SMX 3, while others are new.

1. Renaming the examples. It's not clear which demos use JBI vs OSGi. 
For example 'camel' does but 'camel-nmr' doesn't, while 'camel-osgi' 
doesn't use the NMR but uses OSGi properties. Would some of them benefit 
from renaming?

2. It seems to me, there may be some crossover between some of the 
examples, but there may be subtle things about the demos I'm not picking 
up. This is particularly the case with some of the examples that were in 
the 4.0.0 release and those that are in subversion but didn't make it, 
e.g. cxf-nmr and cxf-nmr-osgi. This might become more apparent when the 
purpose of each demo is clearer.

What do people think?

Hoping to help,

Aidan Hollinshead

Re: Making the SMX 4 examples clearer

["Jamie G." <ja...@gmail.com>]

Hi Aidan,

 I certainly agree with your first three points, the sample README
files can all do with some improvement. As to renaming examples, I
think that clarifying the README files may improve user understanding
as to what is occuring in each demo. I know that in my own experiments
with the 4.0 demos that I have found enabling an exchange listener
useful to catch just what NMR communications are occuring (see NMR
listeners in the NMR kit). I would suggest opening a JIRA improvement
task in SMX4 for each of the README files you would like to improve
for verbosity and clearity.

Cheers,
Jamie
http://icodebythesea.blogspot.com/

On Mon, May 18, 2009 at 9:42 AM, Aidan Hollinshead
<ai...@progress.com> wrote:
> Hi,
>
> As a relative newbie to ServiceMix 4, I was going through the examples and
> saw a few things I thought could perhaps be improved, and I'd like to help
>
> 1. Write a top-level README in the examples directory that lists the demos
> and what they do because it's hard to figure out just from directory names
> where you should start. I'm assuming this would cover the examples that are
> released.
>
> 2. Add a bit more explanatory information to the READMEs and a consistent
> format, including an overview of what the demo does (what particular feature
> or pattern it's demonstrating), what parts make up the example, and which
> config files or code are particularly important to this example, then the
> usual instructions on how to build and/or run the example. I know some of
> the examples, for example do have some more explanation already on
> servicemix.apache.org but that only applies to a couple.
>
> 3. Write READMEs for the examples that weren't in the 4.0.0.0 release but
> are in SVN.
>
> There are some other ideas that are a bit more structural and would thus
> have more side effects. I know some of the examples (bridge, camel &
> cxf-wsdl-first) are carried over from SMX 3, while others are new.
>
> 1. Renaming the examples. It's not clear which demos use JBI vs OSGi. For
> example 'camel' does but 'camel-nmr' doesn't, while 'camel-osgi' doesn't use
> the NMR but uses OSGi properties. Would some of them benefit from renaming?
>
> 2. It seems to me, there may be some crossover between some of the examples,
> but there may be subtle things about the demos I'm not picking up. This is
> particularly the case with some of the examples that were in the 4.0.0
> release and those that are in subversion but didn't make it, e.g. cxf-nmr
> and cxf-nmr-osgi. This might become more apparent when the purpose of each
> demo is clearer.
>
> What do people think?
>
> Hoping to help,
>
> Aidan Hollinshead
>
>