Hi,
Frankly I fully agree with Vivian in this problem.
Together with somebody else, I had to spend quite a lot of time to
understand some things about using SM that were not covered on the website,
and if they were, they were just slightly mentioned. I did use the
discussion forum- searched and asked questions - but it wasn't enough. The
source code is not documented so I could not figure out the problem easily.
Easy as it may be to go through the tutorials, they just show an end result
- but how to get to that result is supposed to be explained in the
documentation. That is, the developer to-do-s (with alternatives) when:
- deploying some components to SM, depending on protocol, methods of
deployment
- detailed explanation of how communication happens from one endpoint to
another - this is actually essential
- details on how endpoint resolution is done by SM
- details on the message processing API; how normalization and
denormalization happen; message formats
- details on available tools like marshaller, etc.
- structured explanation of how EAI patterns are implementable / implemented
by SM
- exactly how SM implements the JBI specification
- details, tune-ups, optimizations on assessing the performance of SM. This
is essential too, for the overall project. The WSO2 people have approached
it already on their side. Why SM doesn’t fight for itself?
The thing is - somebody already worked on all these aspects, and it’s a pity
to have users (developers) waste time in trying to reinvent them, simply
because they can't understand or know how to use the existing ones.
Overall, I think that if we gather a bunch of people ready to help, we can
make an action plan and do this work together to improve the documentation.
I can help, in case there are other people in.
Best,
Gabriela
-----Original Message-----
From: Madesclair Vivian [mailto:[email protected]]
Sent: Thursday, July 16, 2009 4:53 PM
To: [email protected]
Subject: RE: ServiceMix 3 Website Refactoring
Well,
I really agree with the author of this page
(http://servicemix.apache.org/servicemix-3-website-refactoring.html) the
lack of "user" section being the critical point.
However, the global explaination of JBI and servicemix is not what bother me
the most. In fact I saw many time all those diagrams with the BC, SE, etc...
(maybe I saw them too much because I found them when I was looking for
something else). In my opinion, there is also a hudge lack of documentation
between the JBI point of view (high level view) and the developper point of
view. The user point of view has to integrate JBI, but it also has to go a
bit deeper in how servicemix works (there has been a few attempt in filling
that gap, see [1]).
As a user, I do not only need documentation about component (which also has
to be improved, I will talk about it later), but I need to know how
servicemix process message too (MessageExchange, Interceptor, what are
these, how do they relate...). This would help me to understand the
exception or the unexpected behavior I get. I also need to know, in this
process :
- which elements are hard-defined and relate to the "developer part"
- which elements have to be configured by the user (BC via xbeans..) and to
what extent
- which elements are designed to be extended (marshaler...)
I saw there are a lot a tutorials. IMO, detailed tutorial cannot do all the
job, and I have to admit I had special goals so I read the minimum tutorial
to get an idea. I have no time to do all the tutorial, because a very few
part would actually tells me usefull things for my use case. IMO tutorials
are too specifics and will really help only a few users.
Then, in addition to a general part for user, comes the part for components.
I think the documentation for components have to be broader. For exemple, in
the documentation for the HTTP component, links to the documentation of http
marshalers would be welcome, or link to any related content that could be
needed when using a specific component. In some pages of the documentation,
there are many links like that and I really appreciated it.
An other thing that seems tricky is the documentation of different versions.
I am using smx3.3 so I think the documentation is quite uptodate for me. But
I feel like it is not the case for all users. I have not idea how this
should be done, but putting red annotation (for older version) in the last
version of the documentation is confusing.
Finally, I am maybe a bit young to assume that, but I think an ESB play a
role that is at the confluence of many technologies and therefore, there
will always be questions because some people (like me) does not have an
extensive enough knowledge of these technologies. When used on their own,
with frameworks, we often don't need to know very much to make it works. And
when it comes to the ESB, all our lacks are revealed... Well that is only my
opinion of "soon graduated student".
Of course, I don't have an extensive knowledge of the servicemix website and
I might have missed a lot. But maybe if I missed, it is because I felt the
parts would not help me, or maybe the parts where not referenced where I
would have needed them.
If I think of anything more I will tell! This technology (ESB) is really
interesting, and I wish I had time to help...
Best Regards
Vivian
[1] http://servicemix.apache.org/how-stuff-works.html
-----Message d'origine-----
De : Jean-Baptiste Onofré [mailto:[email protected]]
Envoyé : jeudi 16 juillet 2009 15:11
À : [email protected]
Objet : Re: ServiceMix 3 Website Refactoring
Thanks Vivian,
All helps are welcome :)
The best way to provide your feeling is the user mailing list.
Regards
JB
Madesclair Vivian wrote:
Hi,
I just found a page on smx website explaining how the website should be
refactored. I am quite new to smx and ESB in general so I would like to know
where I could give my opinion about that because I think it could help.
Regards,
Vivian MADESCLAIR
Stagiaire - Division Midi-Pyrénées - Agence 103
Sopra group.
Basso Cambo
14 rue Mesplé 31000 Toulouse
Phone : +33 (0)5 61 16 25 06
[email protected] - www.sopragroup.com
<http://www.sopragroup.com/> Ce message peut contenir des informations
confidentielles dont la divulgation est à ce titre rigoureusement interdite
en l'absence d'autorisation explicite de l'émetteur. Dans l'hypothèse où
vous auriez reçu par erreur ce message, merci de le renvoyer à l'émetteur et
de détruire toute copie.
P Pensez à l'environnement avant d'imprimer.
