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.
