You are viewing a plain text version of this content. The canonical link for it is here.
Posted to users@servicemix.apache.org by Madesclair Vivian <vm...@sopragroup.com> on 2009/07/16 14:52:06 UTC
Re: ServiceMix 3 Website Refactoring
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
vmadesclair@sopagroup.com - 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.
RE: ServiceMix 3 Website Refactoring
Posted by Madesclair Vivian <vm...@sopragroup.com>.
Hello,
I saw the mockup for a new smx home page [1] and I have a few comments
about this.
I like the organization and content of the page. But I would add one
more link which would go in the education section (btw education is a
weird name. Maybe "general documentation", "information", "general
questions" would fit better). I would add a "What is ServiceMix" link
that would explain at least :
- What does it do (though a small introduction is provided at the top,
it is not enough I think)
- What does it consist in (a java application, that can run standalone
or in containers.. + components)
IMO this section (education) should not be hidden at the bottom of the
page.
I also think that "develop smx" links are not essentials, because people
that might be interested in it will have already a good knowledge of
servicemix and therefore of its website. So they could be at the bottom
of the page, instead of the "education" section.
Regards,
Vivian
[1] http://servicemix.apache.org/home2.html
Re: ServiceMix 3 Website Refactoring
Posted by Jean-Baptiste Onofré <jb...@nanthrax.net>.
Hi,
Your comments are legitimate and are mostly right.
The best way to improve the content of the website is to raise JIRA
tasks on the different topic. All topics mentioned by Gabriela is good
start.
You have a JIRA component dedicated to document (name is "documentation").
On the website, we have a section "Documentation" containing:
- Getting Started: it should contain where to download, install and
basicly start/stop SMX.
- Tutorials: it should contain SU/SA/OSGi implementation example and
deployment.
- User's Guide: it should contain deeper documentation on the SMX core
(how to setup the deployer, how to tune SMX, what's the classloader
policy, etc). It already contains a lot of information. I think that
this part can be improved.
- Article: external references.
- Cookbook: it should contains FAQ and tips.
I propose to "refactor" the SMX User's Guide and rename it ServiceMix
Manual. This new ServiceMix Manual will retake all information contained
into current User's Guide but in a more professional way.
The Camel Manual looks very well and provide PDF format. For me, it's a
very good documentation and I propose to do the same for ServiceMix. I'm
ready to work on it and especially the build process as made for Camel.
@SMX Team: are you with that ? Can I open a documentation JIRA task on
this topic ?
Thanks
Regards
JB
Gabriela Gheorghe wrote:
> 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:vmadesclair@sopragroup.com]
> Sent: Thursday, July 16, 2009 4:53 PM
> To: users@servicemix.apache.org
> 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:jb@nanthrax.net]
> Envoyé : jeudi 16 juillet 2009 15:11
> À : users@servicemix.apache.org
> 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
>> vmadesclair@sopagroup.com - 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.
>>
>>
>
>
RE: ServiceMix 3 Website Refactoring
Posted by Gabriela Gheorghe <ga...@disi.unitn.it>.
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:vmadesclair@sopragroup.com]
Sent: Thursday, July 16, 2009 4:53 PM
To: users@servicemix.apache.org
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:jb@nanthrax.net]
Envoyé : jeudi 16 juillet 2009 15:11
À : users@servicemix.apache.org
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
> vmadesclair@sopagroup.com - 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.
>
>
RE: ServiceMix 3 Website Refactoring
Posted by Madesclair Vivian <vm...@sopragroup.com>.
One more thing. Everytime somebody asks a how-question on this list, if you can't point him to specific links, it shows a documentation lack. IMO, each lack should be referenced and the response(s!) on the list should be used to write the documentation.
I think a good documentation would save you time on the long range. And people can be pointed at specific documentation by anyone, not only committers.
But, well, as always, easy to say...
-----Message d'origine-----
De : Madesclair Vivian [mailto:vmadesclair@sopragroup.com]
Envoyé : jeudi 16 juillet 2009 16:53
À : users@servicemix.apache.org
Objet : 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:jb@nanthrax.net] Envoyé : jeudi 16 juillet 2009 15:11 À : users@servicemix.apache.org 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
> vmadesclair@sopagroup.com - 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.
>
>
RE: ServiceMix 3 Website Refactoring
Posted by Madesclair Vivian <vm...@sopragroup.com>.
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:jb@nanthrax.net]
Envoyé : jeudi 16 juillet 2009 15:11
À : users@servicemix.apache.org
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
> vmadesclair@sopagroup.com - 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.
>
>
Re: ServiceMix 3 Website Refactoring
Posted by Jean-Baptiste Onofré <jb...@nanthrax.net>.
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
> vmadesclair@sopagroup.com - 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.
>
>
Re: ServiceMix 3 Website Refactoring
Posted by Greg Lucas <gr...@glucas.net>.
Nice - I like the layout and the distinct entry points for smx3, smx4,
and components.
Would 'Use ServiceMix' and 'Develop ServiceMix' link to documentation
or to downloads/source, etc? If they link to doc then perhaps the
'education' section should be more clearly for general/overview
information (perhaps just 'Learn More').
Also +1 with previous comment of making the general education section
more prominent.
--
Greg