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