Documentation Improvements and Reorganization

[Bruce Snyder <br...@gmail.com>]

It occurred to me recently that from a documentation standpoint we
have not explained how to use ServiceMix very well at all to new users
and I think we could make a dramatic improvement with a bit of work
and some reorganization.

Currently, everything is explained from the point of view of someone
who already knows what JBI and ServiceMix provide and focuses largely
on the ServiceMix components. IMO, this is identical to teaching
someone how to swim by throwing them in a pool - the result of which
could be damaging to their perception of swimming for a long time to
come. The same thing happens with ServiceMix today. The first
impression of ServiceMix is that it's difficult to use which is 180
degrees different than the truth.

New users approach ServiceMix trying to understand at a very
fundamental level what ServiceMix offers and how they should use it.
My experience in speaking with folks all over the world has helped me
understand that the most common approach for new users begins by
seeking answers to a question similar to this one:

'I want to connect a system that speaks protocol X to system that
speaks protocol Y, how can I do that with ServiceMix?'

Soon after that, another common question arises:

'What if I want to do processing between the interconnect of X and Y?
How can I do that with ServiceMix?'

If you look at the ServiceMix documentation, the website provides
little to answer these types of questions. New users really have to do
a lot of digging in order to understand how to even approach
ServiceMix.

To fix this, I'd like to start reorganizing the wiki/website to
improve this situation. I'd like to make the website introduce
ServiceMix to new users by answering the questions noted above. I
think that this is relatively easy to do, it will just take some time
to reorganize the current content and put a few new pages in place.
The overall explanation of using ServiceMix should focus on two areas:
supported protocols and supported engines. This will help to answer
the two questions above by providing information on the use cases for
the support of a given protocol in ServiceMix and links to the
components that provide such use cases. But we need to do more than
this.

The ServiceMix home page is a bit overwhelming. There's just simply
too much information being thrown at folks. It's also obvious that the
ServiceMix home page was put together by a bunch of engineers, which
is true, but we need to improve upon it. IMO we should move some of
the current home page content to the Features page. The home page
should be relatively minimal providing:

* info about the goal(s) of the ServiceMix project
** educate folks on JBI and ESBs in general
** buiilding an open source ESB based on JBI
** reuse of the Spring Framework APIs
** etc.
* info specifically for ServiceMix 3
** it's the current stable version
** It's based on JBI
** etc.
* info specifically for ServiceMix 4
** the all new and improved thingy
** it still supports JBI but also now supports OSGi bundles
** etc.
* links for:
** using ServiceMix
** developing ServiceMix
* the last 10 news items (we need to start posting more news)

In the left-hand side navigation, there's a Developers section but not
a Users section. IMO this just points out rather clearly that the
website is too focused on providing information about *developing* the
ServiceMix container and far too slim on content for *using* the
ServiceMix container. I suggest that we improve this by placing two
prominent links on the home page as suggested above; one link for
using ServiceMix and one link for developing ServiceMix. By
emphasizing these two links on the home page, we will more
appropriately address the two major classes of folks who are
interested in ServiceMix.

The users section should focus on educating users about ESBs, JBI and
ServiceMix by including the topics from the current User's Guide and
Tutorials pages for starters, the client API, etc. The developers
section should focus on educating users how to develop JBI components,
core container development and a better dissection and discussion of
the various APIs in ServiceMix (e.g., the JBI APIs, the JBI component
framework, the core ServiceMix container APIs, etc.

Additional improvements for the navigation on the left-hand side include:

* the component list should be removed from the navigation and place
appropriately in the use case pages
* the related projects list should be removed in favor of the related
projects page (which needs be fleshed out more)

Additional improvements:

* the FAQs need a lot of love; we should be covering all of the common
issues and challenges that folks encounter

That's all my brain can dump for now. I'm gonna start reorganizing
some of this information very soon.

Bruce
-- 
perl -e 'print unpack("u30","D0G)U8V4\@4VYY9&5R\"F)R=6-E+G-N>61E<D\!G;6%I;\"YC;VT*"
);'

Apache ActiveMQ - http://activemq.org/
Apache Camel - http://activemq.org/camel/
Apache ServiceMix - http://servicemix.org/
Apache Geronimo - http://geronimo.apache.org/

Blog: http://bruceblog.org/

Re: Documentation Improvements and Reorganization

[Ulhas Bhole <ap...@gmail.com>]

Well written Bruce,
You have well captured the sentiments of the nervous new users (and hoping
to be the SMX contributer) like me. It does overwhelm new users where to
start and how to learn step-by-step.
Looking forward to the new look of the wiki and documentation.

Regards,

Ulhas Bhole

On Sun, Mar 16, 2008 at 6:52 PM, Bruce Snyder <br...@gmail.com>
wrote:

> It occurred to me recently that from a documentation standpoint we
> have not explained how to use ServiceMix very well at all to new users
> and I think we could make a dramatic improvement with a bit of work
> and some reorganization.
>
> Currently, everything is explained from the point of view of someone
> who already knows what JBI and ServiceMix provide and focuses largely
> on the ServiceMix components. IMO, this is identical to teaching
> someone how to swim by throwing them in a pool - the result of which
> could be damaging to their perception of swimming for a long time to
> come. The same thing happens with ServiceMix today. The first
> impression of ServiceMix is that it's difficult to use which is 180
> degrees different than the truth.
>
> New users approach ServiceMix trying to understand at a very
> fundamental level what ServiceMix offers and how they should use it.
> My experience in speaking with folks all over the world has helped me
> understand that the most common approach for new users begins by
> seeking answers to a question similar to this one:
>
> 'I want to connect a system that speaks protocol X to system that
> speaks protocol Y, how can I do that with ServiceMix?'
>
> Soon after that, another common question arises:
>
> 'What if I want to do processing between the interconnect of X and Y?
> How can I do that with ServiceMix?'
>
> If you look at the ServiceMix documentation, the website provides
> little to answer these types of questions. New users really have to do
> a lot of digging in order to understand how to even approach
> ServiceMix.
>
> To fix this, I'd like to start reorganizing the wiki/website to
> improve this situation. I'd like to make the website introduce
> ServiceMix to new users by answering the questions noted above. I
> think that this is relatively easy to do, it will just take some time
> to reorganize the current content and put a few new pages in place.
> The overall explanation of using ServiceMix should focus on two areas:
> supported protocols and supported engines. This will help to answer
> the two questions above by providing information on the use cases for
> the support of a given protocol in ServiceMix and links to the
> components that provide such use cases. But we need to do more than
> this.
>
> The ServiceMix home page is a bit overwhelming. There's just simply
> too much information being thrown at folks. It's also obvious that the
> ServiceMix home page was put together by a bunch of engineers, which
> is true, but we need to improve upon it. IMO we should move some of
> the current home page content to the Features page. The home page
> should be relatively minimal providing:
>
> * info about the goal(s) of the ServiceMix project
> ** educate folks on JBI and ESBs in general
> ** buiilding an open source ESB based on JBI
> ** reuse of the Spring Framework APIs
> ** etc.
> * info specifically for ServiceMix 3
> ** it's the current stable version
> ** It's based on JBI
> ** etc.
> * info specifically for ServiceMix 4
> ** the all new and improved thingy
> ** it still supports JBI but also now supports OSGi bundles
> ** etc.
> * links for:
> ** using ServiceMix
> ** developing ServiceMix
> * the last 10 news items (we need to start posting more news)
>
> In the left-hand side navigation, there's a Developers section but not
> a Users section. IMO this just points out rather clearly that the
> website is too focused on providing information about *developing* the
> ServiceMix container and far too slim on content for *using* the
> ServiceMix container. I suggest that we improve this by placing two
> prominent links on the home page as suggested above; one link for
> using ServiceMix and one link for developing ServiceMix. By
> emphasizing these two links on the home page, we will more
> appropriately address the two major classes of folks who are
> interested in ServiceMix.
>
> The users section should focus on educating users about ESBs, JBI and
> ServiceMix by including the topics from the current User's Guide and
> Tutorials pages for starters, the client API, etc. The developers
> section should focus on educating users how to develop JBI components,
> core container development and a better dissection and discussion of
> the various APIs in ServiceMix (e.g., the JBI APIs, the JBI component
> framework, the core ServiceMix container APIs, etc.
>
> Additional improvements for the navigation on the left-hand side include:
>
> * the component list should be removed from the navigation and place
> appropriately in the use case pages
> * the related projects list should be removed in favor of the related
> projects page (which needs be fleshed out more)
>
> Additional improvements:
>
> * the FAQs need a lot of love; we should be covering all of the common
> issues and challenges that folks encounter
>
> That's all my brain can dump for now. I'm gonna start reorganizing
> some of this information very soon.
>
> Bruce
> --
> perl -e 'print
> unpack("u30","D0G)U8V4\@4VYY9&5R\"F)R=6-E+G-N>61E<D\!G;6%I;\"YC;VT*"
> );'
>
> Apache ActiveMQ - http://activemq.org/
> Apache Camel - http://activemq.org/camel/
> Apache ServiceMix - http://servicemix.org/
> Apache Geronimo - http://geronimo.apache.org/
>
> Blog: http://bruceblog.org/
>

Re: Documentation Improvements and Reorganization

[Chris Custine <cc...@apache.org>]

+1  I think this makes perfect sense and will make things much easier to
find for both new and experienced users.

Chris

On Sun, Mar 16, 2008 at 12:52 PM, Bruce Snyder <br...@gmail.com>
wrote:

> It occurred to me recently that from a documentation standpoint we
> have not explained how to use ServiceMix very well at all to new users
> and I think we could make a dramatic improvement with a bit of work
> and some reorganization.
>
> Currently, everything is explained from the point of view of someone
> who already knows what JBI and ServiceMix provide and focuses largely
> on the ServiceMix components. IMO, this is identical to teaching
> someone how to swim by throwing them in a pool - the result of which
> could be damaging to their perception of swimming for a long time to
> come. The same thing happens with ServiceMix today. The first
> impression of ServiceMix is that it's difficult to use which is 180
> degrees different than the truth.
>
> New users approach ServiceMix trying to understand at a very
> fundamental level what ServiceMix offers and how they should use it.
> My experience in speaking with folks all over the world has helped me
> understand that the most common approach for new users begins by
> seeking answers to a question similar to this one:
>
> 'I want to connect a system that speaks protocol X to system that
> speaks protocol Y, how can I do that with ServiceMix?'
>
> Soon after that, another common question arises:
>
> 'What if I want to do processing between the interconnect of X and Y?
> How can I do that with ServiceMix?'
>
> If you look at the ServiceMix documentation, the website provides
> little to answer these types of questions. New users really have to do
> a lot of digging in order to understand how to even approach
> ServiceMix.
>
> To fix this, I'd like to start reorganizing the wiki/website to
> improve this situation. I'd like to make the website introduce
> ServiceMix to new users by answering the questions noted above. I
> think that this is relatively easy to do, it will just take some time
> to reorganize the current content and put a few new pages in place.
> The overall explanation of using ServiceMix should focus on two areas:
> supported protocols and supported engines. This will help to answer
> the two questions above by providing information on the use cases for
> the support of a given protocol in ServiceMix and links to the
> components that provide such use cases. But we need to do more than
> this.
>
> The ServiceMix home page is a bit overwhelming. There's just simply
> too much information being thrown at folks. It's also obvious that the
> ServiceMix home page was put together by a bunch of engineers, which
> is true, but we need to improve upon it. IMO we should move some of
> the current home page content to the Features page. The home page
> should be relatively minimal providing:
>
> * info about the goal(s) of the ServiceMix project
> ** educate folks on JBI and ESBs in general
> ** buiilding an open source ESB based on JBI
> ** reuse of the Spring Framework APIs
> ** etc.
> * info specifically for ServiceMix 3
> ** it's the current stable version
> ** It's based on JBI
> ** etc.
> * info specifically for ServiceMix 4
> ** the all new and improved thingy
> ** it still supports JBI but also now supports OSGi bundles
> ** etc.
> * links for:
> ** using ServiceMix
> ** developing ServiceMix
> * the last 10 news items (we need to start posting more news)
>
> In the left-hand side navigation, there's a Developers section but not
> a Users section. IMO this just points out rather clearly that the
> website is too focused on providing information about *developing* the
> ServiceMix container and far too slim on content for *using* the
> ServiceMix container. I suggest that we improve this by placing two
> prominent links on the home page as suggested above; one link for
> using ServiceMix and one link for developing ServiceMix. By
> emphasizing these two links on the home page, we will more
> appropriately address the two major classes of folks who are
> interested in ServiceMix.
>
> The users section should focus on educating users about ESBs, JBI and
> ServiceMix by including the topics from the current User's Guide and
> Tutorials pages for starters, the client API, etc. The developers
> section should focus on educating users how to develop JBI components,
> core container development and a better dissection and discussion of
> the various APIs in ServiceMix (e.g., the JBI APIs, the JBI component
> framework, the core ServiceMix container APIs, etc.
>
> Additional improvements for the navigation on the left-hand side include:
>
> * the component list should be removed from the navigation and place
> appropriately in the use case pages
> * the related projects list should be removed in favor of the related
> projects page (which needs be fleshed out more)
>
> Additional improvements:
>
> * the FAQs need a lot of love; we should be covering all of the common
> issues and challenges that folks encounter
>
> That's all my brain can dump for now. I'm gonna start reorganizing
> some of this information very soon.
>
> Bruce
> --
> perl -e 'print
> unpack("u30","D0G)U8V4\@4VYY9&5R\"F)R=6-E+G-N>61E<D\!G;6%I;\"YC;VT*"
> );'
>
> Apache ActiveMQ - http://activemq.org/
> Apache Camel - http://activemq.org/camel/
> Apache ServiceMix - http://servicemix.org/
> Apache Geronimo - http://geronimo.apache.org/
>
> Blog: http://bruceblog.org/
>

Re: Documentation Improvements and Reorganization

[Edell Nolan <ed...@gmail.com>]

Hi,

+1 - As a newbie to SMX this would be great as I have found it hard to get
information.
You have to dig around the site quite a bit.

Edell.


On 3/17/08, Lars Heinemann <la...@compart.net> wrote:
>
> Bruce,
>
> what you wrote is correct. I remember the problems I faced when starting
> to use smx.
> At this time there was even less documentation than now. It is really
> hard to
> step in and understanding what and how to do it with smx.
> The proposed separation and the new slim home page makes sense to me.
>
> Regards,
> Lars
>
>
>
>
> Bruce Snyder schrieb:
> > It occurred to me recently that from a documentation standpoint we
> > have not explained how to use ServiceMix very well at all to new users
> > and I think we could make a dramatic improvement with a bit of work
> > and some reorganization.
> >
> > Currently, everything is explained from the point of view of someone
> > who already knows what JBI and ServiceMix provide and focuses largely
> > on the ServiceMix components. IMO, this is identical to teaching
> > someone how to swim by throwing them in a pool - the result of which
> > could be damaging to their perception of swimming for a long time to
> > come. The same thing happens with ServiceMix today. The first
> > impression of ServiceMix is that it's difficult to use which is 180
> > degrees different than the truth.
> >
> > New users approach ServiceMix trying to understand at a very
> > fundamental level what ServiceMix offers and how they should use it.
> > My experience in speaking with folks all over the world has helped me
> > understand that the most common approach for new users begins by
> > seeking answers to a question similar to this one:
> >
> > 'I want to connect a system that speaks protocol X to system that
> > speaks protocol Y, how can I do that with ServiceMix?'
> >
> > Soon after that, another common question arises:
> >
> > 'What if I want to do processing between the interconnect of X and Y?
> > How can I do that with ServiceMix?'
> >
> > If you look at the ServiceMix documentation, the website provides
> > little to answer these types of questions. New users really have to do
> > a lot of digging in order to understand how to even approach
> > ServiceMix.
> >
> > To fix this, I'd like to start reorganizing the wiki/website to
> > improve this situation. I'd like to make the website introduce
> > ServiceMix to new users by answering the questions noted above. I
> > think that this is relatively easy to do, it will just take some time
> > to reorganize the current content and put a few new pages in place.
> > The overall explanation of using ServiceMix should focus on two areas:
> > supported protocols and supported engines. This will help to answer
> > the two questions above by providing information on the use cases for
> > the support of a given protocol in ServiceMix and links to the
> > components that provide such use cases. But we need to do more than
> > this.
> >
> > The ServiceMix home page is a bit overwhelming. There's just simply
> > too much information being thrown at folks. It's also obvious that the
> > ServiceMix home page was put together by a bunch of engineers, which
> > is true, but we need to improve upon it. IMO we should move some of
> > the current home page content to the Features page. The home page
> > should be relatively minimal providing:
> >
> > * info about the goal(s) of the ServiceMix project
> > ** educate folks on JBI and ESBs in general
> > ** buiilding an open source ESB based on JBI
> > ** reuse of the Spring Framework APIs
> > ** etc.
> > * info specifically for ServiceMix 3
> > ** it's the current stable version
> > ** It's based on JBI
> > ** etc.
> > * info specifically for ServiceMix 4
> > ** the all new and improved thingy
> > ** it still supports JBI but also now supports OSGi bundles
> > ** etc.
> > * links for:
> > ** using ServiceMix
> > ** developing ServiceMix
> > * the last 10 news items (we need to start posting more news)
> >
> > In the left-hand side navigation, there's a Developers section but not
> > a Users section. IMO this just points out rather clearly that the
> > website is too focused on providing information about *developing* the
> > ServiceMix container and far too slim on content for *using* the
> > ServiceMix container. I suggest that we improve this by placing two
> > prominent links on the home page as suggested above; one link for
> > using ServiceMix and one link for developing ServiceMix. By
> > emphasizing these two links on the home page, we will more
> > appropriately address the two major classes of folks who are
> > interested in ServiceMix.
> >
> > The users section should focus on educating users about ESBs, JBI and
> > ServiceMix by including the topics from the current User's Guide and
> > Tutorials pages for starters, the client API, etc. The developers
> > section should focus on educating users how to develop JBI components,
> > core container development and a better dissection and discussion of
> > the various APIs in ServiceMix (e.g., the JBI APIs, the JBI component
> > framework, the core ServiceMix container APIs, etc.
> >
> > Additional improvements for the navigation on the left-hand side
> include:
> >
> > * the component list should be removed from the navigation and place
> > appropriately in the use case pages
> > * the related projects list should be removed in favor of the related
> > projects page (which needs be fleshed out more)
> >
> > Additional improvements:
> >
> > * the FAQs need a lot of love; we should be covering all of the common
> > issues and challenges that folks encounter
> >
> > That's all my brain can dump for now. I'm gonna start reorganizing
> > some of this information very soon.
> >
> > Bruce
> >
>

Re: Documentation Improvements and Reorganization

[lhein <lh...@apache.org>]

Bruce,

maybe it would be a good thing to first make a design of the new structure
and discuss it here before starting to change the whole site now. When doing
so also other people can help finish this work so you are not the only one
working on it.

Regards,
Lars



lhe77 wrote:
> 
> Bruce,
> 
> what you wrote is correct. I remember the problems I faced when starting
> to use smx.
> At this time there was even less documentation than now. It is really
> hard to
> step in and understanding what and how to do it with smx.
> The proposed separation and the new slim home page makes sense to me.
> 
> Regards,
> Lars
> 
> 
> 
> 
> Bruce Snyder schrieb:
>> It occurred to me recently that from a documentation standpoint we
>> have not explained how to use ServiceMix very well at all to new users
>> and I think we could make a dramatic improvement with a bit of work
>> and some reorganization.
>>
>> Currently, everything is explained from the point of view of someone
>> who already knows what JBI and ServiceMix provide and focuses largely
>> on the ServiceMix components. IMO, this is identical to teaching
>> someone how to swim by throwing them in a pool - the result of which
>> could be damaging to their perception of swimming for a long time to
>> come. The same thing happens with ServiceMix today. The first
>> impression of ServiceMix is that it's difficult to use which is 180
>> degrees different than the truth.
>>
>> New users approach ServiceMix trying to understand at a very
>> fundamental level what ServiceMix offers and how they should use it.
>> My experience in speaking with folks all over the world has helped me
>> understand that the most common approach for new users begins by
>> seeking answers to a question similar to this one:
>>
>> 'I want to connect a system that speaks protocol X to system that
>> speaks protocol Y, how can I do that with ServiceMix?'
>>
>> Soon after that, another common question arises:
>>
>> 'What if I want to do processing between the interconnect of X and Y?
>> How can I do that with ServiceMix?'
>>
>> If you look at the ServiceMix documentation, the website provides
>> little to answer these types of questions. New users really have to do
>> a lot of digging in order to understand how to even approach
>> ServiceMix.
>>
>> To fix this, I'd like to start reorganizing the wiki/website to
>> improve this situation. I'd like to make the website introduce
>> ServiceMix to new users by answering the questions noted above. I
>> think that this is relatively easy to do, it will just take some time
>> to reorganize the current content and put a few new pages in place.
>> The overall explanation of using ServiceMix should focus on two areas:
>> supported protocols and supported engines. This will help to answer
>> the two questions above by providing information on the use cases for
>> the support of a given protocol in ServiceMix and links to the
>> components that provide such use cases. But we need to do more than
>> this.
>>
>> The ServiceMix home page is a bit overwhelming. There's just simply
>> too much information being thrown at folks. It's also obvious that the
>> ServiceMix home page was put together by a bunch of engineers, which
>> is true, but we need to improve upon it. IMO we should move some of
>> the current home page content to the Features page. The home page
>> should be relatively minimal providing:
>>
>> * info about the goal(s) of the ServiceMix project
>> ** educate folks on JBI and ESBs in general
>> ** buiilding an open source ESB based on JBI
>> ** reuse of the Spring Framework APIs
>> ** etc.
>> * info specifically for ServiceMix 3
>> ** it's the current stable version
>> ** It's based on JBI
>> ** etc.
>> * info specifically for ServiceMix 4
>> ** the all new and improved thingy
>> ** it still supports JBI but also now supports OSGi bundles
>> ** etc.
>> * links for:
>> ** using ServiceMix
>> ** developing ServiceMix
>> * the last 10 news items (we need to start posting more news)
>>
>> In the left-hand side navigation, there's a Developers section but not
>> a Users section. IMO this just points out rather clearly that the
>> website is too focused on providing information about *developing* the
>> ServiceMix container and far too slim on content for *using* the
>> ServiceMix container. I suggest that we improve this by placing two
>> prominent links on the home page as suggested above; one link for
>> using ServiceMix and one link for developing ServiceMix. By
>> emphasizing these two links on the home page, we will more
>> appropriately address the two major classes of folks who are
>> interested in ServiceMix.
>>
>> The users section should focus on educating users about ESBs, JBI and
>> ServiceMix by including the topics from the current User's Guide and
>> Tutorials pages for starters, the client API, etc. The developers
>> section should focus on educating users how to develop JBI components,
>> core container development and a better dissection and discussion of
>> the various APIs in ServiceMix (e.g., the JBI APIs, the JBI component
>> framework, the core ServiceMix container APIs, etc.
>>
>> Additional improvements for the navigation on the left-hand side include:
>>
>> * the component list should be removed from the navigation and place
>> appropriately in the use case pages
>> * the related projects list should be removed in favor of the related
>> projects page (which needs be fleshed out more)
>>
>> Additional improvements:
>>
>> * the FAQs need a lot of love; we should be covering all of the common
>> issues and challenges that folks encounter
>>
>> That's all my brain can dump for now. I'm gonna start reorganizing
>> some of this information very soon.
>>
>> Bruce
>>   
> 
> 

-- 
View this message in context: http://www.nabble.com/Documentation-Improvements-and-Reorganization-tp16082514s12049p16090701.html
Sent from the ServiceMix - Dev mailing list archive at Nabble.com.

Re: Documentation Improvements and Reorganization

[Lars Heinemann <la...@compart.net>]

Bruce,

what you wrote is correct. I remember the problems I faced when starting
to use smx.
At this time there was even less documentation than now. It is really
hard to
step in and understanding what and how to do it with smx.
The proposed separation and the new slim home page makes sense to me.

Regards,
Lars




Bruce Snyder schrieb:
> It occurred to me recently that from a documentation standpoint we
> have not explained how to use ServiceMix very well at all to new users
> and I think we could make a dramatic improvement with a bit of work
> and some reorganization.
>
> Currently, everything is explained from the point of view of someone
> who already knows what JBI and ServiceMix provide and focuses largely
> on the ServiceMix components. IMO, this is identical to teaching
> someone how to swim by throwing them in a pool - the result of which
> could be damaging to their perception of swimming for a long time to
> come. The same thing happens with ServiceMix today. The first
> impression of ServiceMix is that it's difficult to use which is 180
> degrees different than the truth.
>
> New users approach ServiceMix trying to understand at a very
> fundamental level what ServiceMix offers and how they should use it.
> My experience in speaking with folks all over the world has helped me
> understand that the most common approach for new users begins by
> seeking answers to a question similar to this one:
>
> 'I want to connect a system that speaks protocol X to system that
> speaks protocol Y, how can I do that with ServiceMix?'
>
> Soon after that, another common question arises:
>
> 'What if I want to do processing between the interconnect of X and Y?
> How can I do that with ServiceMix?'
>
> If you look at the ServiceMix documentation, the website provides
> little to answer these types of questions. New users really have to do
> a lot of digging in order to understand how to even approach
> ServiceMix.
>
> To fix this, I'd like to start reorganizing the wiki/website to
> improve this situation. I'd like to make the website introduce
> ServiceMix to new users by answering the questions noted above. I
> think that this is relatively easy to do, it will just take some time
> to reorganize the current content and put a few new pages in place.
> The overall explanation of using ServiceMix should focus on two areas:
> supported protocols and supported engines. This will help to answer
> the two questions above by providing information on the use cases for
> the support of a given protocol in ServiceMix and links to the
> components that provide such use cases. But we need to do more than
> this.
>
> The ServiceMix home page is a bit overwhelming. There's just simply
> too much information being thrown at folks. It's also obvious that the
> ServiceMix home page was put together by a bunch of engineers, which
> is true, but we need to improve upon it. IMO we should move some of
> the current home page content to the Features page. The home page
> should be relatively minimal providing:
>
> * info about the goal(s) of the ServiceMix project
> ** educate folks on JBI and ESBs in general
> ** buiilding an open source ESB based on JBI
> ** reuse of the Spring Framework APIs
> ** etc.
> * info specifically for ServiceMix 3
> ** it's the current stable version
> ** It's based on JBI
> ** etc.
> * info specifically for ServiceMix 4
> ** the all new and improved thingy
> ** it still supports JBI but also now supports OSGi bundles
> ** etc.
> * links for:
> ** using ServiceMix
> ** developing ServiceMix
> * the last 10 news items (we need to start posting more news)
>
> In the left-hand side navigation, there's a Developers section but not
> a Users section. IMO this just points out rather clearly that the
> website is too focused on providing information about *developing* the
> ServiceMix container and far too slim on content for *using* the
> ServiceMix container. I suggest that we improve this by placing two
> prominent links on the home page as suggested above; one link for
> using ServiceMix and one link for developing ServiceMix. By
> emphasizing these two links on the home page, we will more
> appropriately address the two major classes of folks who are
> interested in ServiceMix.
>
> The users section should focus on educating users about ESBs, JBI and
> ServiceMix by including the topics from the current User's Guide and
> Tutorials pages for starters, the client API, etc. The developers
> section should focus on educating users how to develop JBI components,
> core container development and a better dissection and discussion of
> the various APIs in ServiceMix (e.g., the JBI APIs, the JBI component
> framework, the core ServiceMix container APIs, etc.
>
> Additional improvements for the navigation on the left-hand side include:
>
> * the component list should be removed from the navigation and place
> appropriately in the use case pages
> * the related projects list should be removed in favor of the related
> projects page (which needs be fleshed out more)
>
> Additional improvements:
>
> * the FAQs need a lot of love; we should be covering all of the common
> issues and challenges that folks encounter
>
> That's all my brain can dump for now. I'm gonna start reorganizing
> some of this information very soon.
>
> Bruce
>   

Re: Documentation Improvements and Reorganization

[Bruce Snyder <br...@gmail.com>]

On Wed, Mar 19, 2008 at 11:03 AM, Guillaume Nodet <gn...@gmail.com> wrote:
> Note that imho, most of the documentation is related to using existing
>  ServiceMix components, which will be mostly identical for ServiceMix 3 and
>  ServiceMix 4.   Of course, there will be differences for things related to
>  the container itself.  Anyway, +1 to reorg the site.

Yes, I agree. I believe that we're going to have to split the
components into a separate subproject at some point soon so that they
can be developed independent of either the SMX 3 or SMX 4 containers.
But that's a different topic.

Bruce
-- 
perl -e 'print unpack("u30","D0G)U8V4\@4VYY9&5R\"F)R=6-E+G-N>61E<D\!G;6%I;\"YC;VT*"
);'

Apache ActiveMQ - http://activemq.org/
Apache Camel - http://activemq.org/camel/
Apache ServiceMix - http://servicemix.org/
Apache Geronimo - http://geronimo.apache.org/

Blog: http://bruceblog.org/

Re: Documentation Improvements and Reorganization

[Guillaume Nodet <gn...@gmail.com>]

Note that imho, most of the documentation is related to using existing
ServiceMix components, which will be mostly identical for ServiceMix 3 and
ServiceMix 4.   Of course, there will be differences for things related to
the container itself.  Anyway, +1 to reorg the site.

On Mon, Mar 17, 2008 at 9:30 PM, Bruce Snyder <br...@gmail.com>
wrote:

> On Mon, Mar 17, 2008 at 2:24 PM, Gert Vanthienen
> <ge...@skynet.be> wrote:
> > Bruce,
> >
> >  +1 on your suggestions for improving the structure of the SMX3/4
> websites.
>
> I'm only thinking about SMX 3 right now. After the website is
> restructured I'd like to start an effort to clean up Checkstyle errors
> and dramatically improve the Javadocs and comments in the code. The
> SMX 4 docs is a whole different topic.
>
> Bruce
> --
> perl -e 'print
> unpack("u30","D0G)U8V4\@4VYY9&5R\"F)R=6-E+G-N>61E<D\!G;6%I;\"YC;VT*"
> );'
>
> Apache ActiveMQ - http://activemq.org/
> Apache Camel - http://activemq.org/camel/
> Apache ServiceMix - http://servicemix.org/
> Apache Geronimo - http://geronimo.apache.org/
>
> Blog: http://bruceblog.org/
>



-- 
Cheers,
Guillaume Nodet
------------------------
Blog: http://gnodet.blogspot.com/

Re: Documentation Improvements and Reorganization

[Bruce Snyder <br...@gmail.com>]

On Mon, Mar 17, 2008 at 2:24 PM, Gert Vanthienen
<ge...@skynet.be> wrote:
> Bruce,
>
>  +1 on your suggestions for improving the structure of the SMX3/4 websites.

I'm only thinking about SMX 3 right now. After the website is
restructured I'd like to start an effort to clean up Checkstyle errors
and dramatically improve the Javadocs and comments in the code. The
SMX 4 docs is a whole different topic.

Bruce
-- 
perl -e 'print unpack("u30","D0G)U8V4\@4VYY9&5R\"F)R=6-E+G-N>61E<D\!G;6%I;\"YC;VT*"
);'

Apache ActiveMQ - http://activemq.org/
Apache Camel - http://activemq.org/camel/
Apache ServiceMix - http://servicemix.org/
Apache Geronimo - http://geronimo.apache.org/

Blog: http://bruceblog.org/

Re: Documentation Improvements and Reorganization

[Gert Vanthienen <ge...@skynet.be>]

Bruce,

+1 on your suggestions for improving the structure of the SMX3/4 websites. 

Gert

Bruce Snyder wrote:
> It occurred to me recently that from a documentation standpoint we
> have not explained how to use ServiceMix very well at all to new users
> and I think we could make a dramatic improvement with a bit of work
> and some reorganization.
>
> Currently, everything is explained from the point of view of someone
> who already knows what JBI and ServiceMix provide and focuses largely
> on the ServiceMix components. IMO, this is identical to teaching
> someone how to swim by throwing them in a pool - the result of which
> could be damaging to their perception of swimming for a long time to
> come. The same thing happens with ServiceMix today. The first
> impression of ServiceMix is that it's difficult to use which is 180
> degrees different than the truth.
>
> New users approach ServiceMix trying to understand at a very
> fundamental level what ServiceMix offers and how they should use it.
> My experience in speaking with folks all over the world has helped me
> understand that the most common approach for new users begins by
> seeking answers to a question similar to this one:
>
> 'I want to connect a system that speaks protocol X to system that
> speaks protocol Y, how can I do that with ServiceMix?'
>
> Soon after that, another common question arises:
>
> 'What if I want to do processing between the interconnect of X and Y?
> How can I do that with ServiceMix?'
>
> If you look at the ServiceMix documentation, the website provides
> little to answer these types of questions. New users really have to do
> a lot of digging in order to understand how to even approach
> ServiceMix.
>
> To fix this, I'd like to start reorganizing the wiki/website to
> improve this situation. I'd like to make the website introduce
> ServiceMix to new users by answering the questions noted above. I
> think that this is relatively easy to do, it will just take some time
> to reorganize the current content and put a few new pages in place.
> The overall explanation of using ServiceMix should focus on two areas:
> supported protocols and supported engines. This will help to answer
> the two questions above by providing information on the use cases for
> the support of a given protocol in ServiceMix and links to the
> components that provide such use cases. But we need to do more than
> this.
>
> The ServiceMix home page is a bit overwhelming. There's just simply
> too much information being thrown at folks. It's also obvious that the
> ServiceMix home page was put together by a bunch of engineers, which
> is true, but we need to improve upon it. IMO we should move some of
> the current home page content to the Features page. The home page
> should be relatively minimal providing:
>
> * info about the goal(s) of the ServiceMix project
> ** educate folks on JBI and ESBs in general
> ** buiilding an open source ESB based on JBI
> ** reuse of the Spring Framework APIs
> ** etc.
> * info specifically for ServiceMix 3
> ** it's the current stable version
> ** It's based on JBI
> ** etc.
> * info specifically for ServiceMix 4
> ** the all new and improved thingy
> ** it still supports JBI but also now supports OSGi bundles
> ** etc.
> * links for:
> ** using ServiceMix
> ** developing ServiceMix
> * the last 10 news items (we need to start posting more news)
>
> In the left-hand side navigation, there's a Developers section but not
> a Users section. IMO this just points out rather clearly that the
> website is too focused on providing information about *developing* the
> ServiceMix container and far too slim on content for *using* the
> ServiceMix container. I suggest that we improve this by placing two
> prominent links on the home page as suggested above; one link for
> using ServiceMix and one link for developing ServiceMix. By
> emphasizing these two links on the home page, we will more
> appropriately address the two major classes of folks who are
> interested in ServiceMix.
>
> The users section should focus on educating users about ESBs, JBI and
> ServiceMix by including the topics from the current User's Guide and
> Tutorials pages for starters, the client API, etc. The developers
> section should focus on educating users how to develop JBI components,
> core container development and a better dissection and discussion of
> the various APIs in ServiceMix (e.g., the JBI APIs, the JBI component
> framework, the core ServiceMix container APIs, etc.
>
> Additional improvements for the navigation on the left-hand side include:
>
> * the component list should be removed from the navigation and place
> appropriately in the use case pages
> * the related projects list should be removed in favor of the related
> projects page (which needs be fleshed out more)
>
> Additional improvements:
>
> * the FAQs need a lot of love; we should be covering all of the common
> issues and challenges that folks encounter
>
> That's all my brain can dump for now. I'm gonna start reorganizing
> some of this information very soon.
>
> Bruce
>