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 doesnt fight for itself? The thing is - somebody already worked on all these aspects, and its 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. > >
