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
- {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, WikiMedia 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.
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 - SE is started but needs some contribution to be completed
- CIMERO Editor plugin
- 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