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)[EMAIL
PROTECTED]&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/
