Tutorial Suggestions

[nhcoder <an...@hotmail.com>]

Hi,

If this isn't the right place to post this info please move this message to
the correct place.  

I have gone through both chapter 1 and chapter 2 of the tutorials thus far. 
Both times I ended up with examples that didn't - and still don't - work. 

There are two things that I think would be very helpful:

1) Step by step instructions that make it very clear what you should do at
each step.  The tutorial already does have that in some ways, but the bigger
problem is when the tutorial says something to the effect of "Do this and if
you have problems look at this other page."  That really isn't what a
tutorial is about.  If you want to get rid of the frustration that a new
user is trying to overcome when working with ServiceMix, be very detailed
with what needs to happen at every step of the way.  Since ServiceMix has
several components and technologies that it is trying to bind together it is
very easy for information overload to occur.   This means the contents of
every change to a file and exactly what is typed on the command line in
addition to what directory it should be in should be shown.

2) A final directory structure of all the completed files in an exercise. 
The chapter 2 example didn't say anything about adding the namespace
definition to the other xml files.  While this might be looked at as
something that may be obvious it wasn't.  Eventually I saw it and fixed it
but it would have been helpful to have an "answer key" for the tutorial that
is known to work.  Since the example is built on incremental changes all it
takes is for one step to be off but one small thing and then everything
after that point won't work.

Anyway, I hope these items would be added to the tutorial because it looks
like ServiceMix has a lot of power but if the simplest examples can't be
made to work then it can get very frustrating for a new user.

Thanks,

Andy
-- 
View this message in context: http://www.nabble.com/Tutorial-Suggestions-tp22991657p22991657.html
Sent from the ServiceMix - User mailing list archive at Nabble.com.

Re: Tutorial Suggestions

[Jean-Baptiste Onofré <jb...@nanthrax.net>]

Hi Andy,

We have noted your comment. We will make review on different tutorial 
pages and improve the content.

Feel free to add Jira tasks around this, we will do our best to provide 
a better documentation.

We have begun to discuss (on the dev mailing list) around  documentation 
(content, presentation, tools, etc) and we know that it's a part that we 
need to improve.

Regards
JB

nhcoder wrote:
> Hi,
> 
> If this isn't the right place to post this info please move this message to
> the correct place.  
> 
> I have gone through both chapter 1 and chapter 2 of the tutorials thus far. 
> Both times I ended up with examples that didn't - and still don't - work. 
> 
> There are two things that I think would be very helpful:
> 
> 1) Step by step instructions that make it very clear what you should do at
> each step.  The tutorial already does have that in some ways, but the bigger
> problem is when the tutorial says something to the effect of "Do this and if
> you have problems look at this other page."  That really isn't what a
> tutorial is about.  If you want to get rid of the frustration that a new
> user is trying to overcome when working with ServiceMix, be very detailed
> with what needs to happen at every step of the way.  Since ServiceMix has
> several components and technologies that it is trying to bind together it is
> very easy for information overload to occur.   This means the contents of
> every change to a file and exactly what is typed on the command line in
> addition to what directory it should be in should be shown.
> 
> 2) A final directory structure of all the completed files in an exercise. 
> The chapter 2 example didn't say anything about adding the namespace
> definition to the other xml files.  While this might be looked at as
> something that may be obvious it wasn't.  Eventually I saw it and fixed it
> but it would have been helpful to have an "answer key" for the tutorial that
> is known to work.  Since the example is built on incremental changes all it
> takes is for one step to be off but one small thing and then everything
> after that point won't work.
> 
> Anyway, I hope these items would be added to the tutorial because it looks
> like ServiceMix has a lot of power but if the simplest examples can't be
> made to work then it can get very frustrating for a new user.
> 
> Thanks,
> 
> Andy

-- 
Jean-Baptiste Onofré
---------------------------------
  HomePage
http://www.nanthrax.net
---------------------------------
  Contacts
jbonofre@apache.org
jb@nanthrax.net
---------------------------------
  OpenSource
BuildProcess/AutoDeploy
http://buildprocess.sourceforge.net
Apache ServiceMix
http://servicemix.apache.org
-----------------------------------
PGP : 17D4F086