ServiceMix 3 Website Refactoring

The ServiceMix website needs to be refactored to provide better information to new users, to better organize what is already there and to more appropriately situate the introduction of SMX 4 and refactor SMX 3. Below is the desription I sent to the dev list describing this work:

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

Additional Info

Some work has already been done toward the completion of this goal, including some experimentation with the Confluence wiki and a new ServiceMix home page using the wiki. Unfortunately the wiki is too restrictive to do what we want and need, so a few static HTML pages will be used as a launch point for the ServiceMix project into the SMX 3 project, the SMX 4 project and the SMX Components project.

Keeping three separate projects will better organize everything and maybe even allow the project to eventually start versioning the documentation. The static website needs to be very clean, very organized and very minimal. It will only serve as a launch point for all the information about ServiceMix.

Once the website refactoring is fairly complete, then the ServiceMix 3 Project Refactoring will take place.