Ideas concerning documentation

Here are collected ideas how the documentation may be improved. Feel free to work on any of the tasks or add new ones - in case you have and want no confluence login, just leave a comment at the bottom of the page. And, by the way, developers as well as total freshmen can contribute to the documentation, as questions/suggestions are as important as the answers.

Todo

Incorporate suggestions of http://www.nabble.com/User-Feedback-Request-tf2356023.html into this document. 

Concerning structure and organization

The page Documentation (more correctly: it's children) desperately needs to be re-organized and extended with brief information for each entry. The latter requires to add one of these two options

• {excerpt}summary apperaing{excerpt}
• {excerpt:hidden=true}summary, not be displayed on the page.{excerpt}

to the children pages. See http://goopen.org/confluence/renderer/notationhelp.action?section=confluence for further information.

Cross-referencing pages where appropriate. Use one single information piece/location instead of redundand content on multiple pages (is there some sort of content-pieces-reuse supported by confluence like Typo3, MediaWiki etc. allow?? include works only for whole pages, excerpt allows only one piece per page). Redundand content is bad, as often only one version is updated, but all other occurences of the same information stay outdated/incorrect.

• 3. Installation contains most (but not all) information from Building. Consolidate in one.

Several tutorials etc. are related to one specific ServiceMix version but do not mention this. Include this info in the title page, duplicate the page and change the duplicate to suit the current version.

Add links to CIMERO Editor plugin where appropriate (ideas: User Guide, Docu, Download,...). It's helping newbies a lot.

Concerning content

Pages that need a clean-up

e.g. formatting, adaption to new ServiceMix version, sequence of content,...

• JConsole / JMX Console / JMX management

Pages that are missing blocks of content

Those tutorials, descriptions etc. exist but are not (any more) complete. If possible, a {note} shall be placed where content is missing, so readers get aware of the missing parts.

• Hello World - BC and Hello World - SE are nearly complete but need a bit more content to be complete.
• CIMERO Editor plugin has nearly no docu (except for 2 very good SWFs). Some troubleshooting help needed.
• Nearly all example pages do not help / describe enough for newbies.
• Many examples lack comments in the source code (what does a method/XML-entity do? Why is it needed? Was it created manually or by archetypes?). List todo items here.

Content that is missing completely

• Using out of the box functionality (http component, jsr181 comp, eip comp,...) to create an own SA
• List Maven archetypes and when to use which
• List all available components and give some information about them (type, purpose, usage in any example,...)
• undeployment, see http://mail-archives.apache.org/mod_mbox/geronimo-servicemix-dev/200610.mbox/%3cb23ecedc0610011247v7b435be0ka00ee8e8375230e9@mail.gmail.com%3e
• a central debugging page listing the possibilities and linking to the appropriate pages/sections.
  • run SMix from source in Eclipse in debug mode
  • (permanent) increase the log level to debug in %SERVICEMIX_HOME%\conf\log4j.xml (by changing everything from "info" to "debug") or (temporarily) using JConsole and watch the log file
  • Eclipse WTP server start in debug mode
  • remote debugging of the JVM (default port 5005, can be altered in servicemix.bat in line set DEFAULT_JAVA_DEBUG_OPTS=) by first calling set SERVICEMIX_DEGUG=true then servicemix.bat
  • component debugging in eclipse: To debug serviceMix components, you want to create a project containing the source code. After that, uncomment the line where remote debugging is enabled in servicemix.bat, and run servicemix. After that, use eclipse to connect a remote debugger, set a break point in your components source code, and trigger a dataflow so that your component gets run. Hey presto!
    Source: 2nd comment at http://fiveclouds.blogspot.com/2006/01/spent-one-of-those-days-waiting-for.html
  • your idea
• short text telling what SMix is better suited for than the competitors (mule, celtix, webshpere,...). Maybe in form of use cases? Or in terms of missing features, performance, price, ...?
• (just copy & pasted here, review whether still applicable!) E.g. How do I use the JDBC binding component? How is it configured? What are all the options?