Hi,
Instead of a starter guide, I would suggest that we have an Admin guide
otherwise we will have a gap between Admin and Starter Guide and that we
embed the content of Karaf manual in the Admin guide. This will avoid
the existing confusion about ServiceMix <-> Karaf which still exist
today. Karaf is part of ServiceMix and should be included like that in
the doc. So I propose the following Table of content for the doc :
Starter Guide could become a How To Discover in 5 steps ServiceMix 4 !
1. User Guide
1.1 - Conceptual and Architecture design (osgi intro, messaging
architecture, osgi architecture, messaging + osgi architecture, web
architecture, bundles limitations, ...)
1.2 - Camel (How to use camel on OSGI platform, simple camel project
with Spring-DM or Blueprint, camel + jms, camel + cxf, camel + nmr)
1.3 - JBI (jbi presentation, description of the different jbi
components, engines, ..., bridge jbi with camel, cluster)
1.4 - Transaction and security (Aries transaction management, ex using
camel + jpa)
1.5 - Web
1.6 - Debug and testing
1.7 - Packaging
1.8 - Source and Build
2.1 Admin Guide
2.2 - Installation / Uninstallation
2.3 - Setup Smx as a service on Win2K / Unix machine
2.4 - ServiceMix unmasked (description of the directories, explanation
of the different config files)
2.5 - Administration (= explain different command like man pages on unix
with example)
2.6 - Deployment (explain different mechanisms : hot deploy,
osgi:install, provisioning)
2.7 - Connection mode (client/server, client only, ssh, web console, how
to use command line)
2.8 - High availability - clustering (instances creation, setup lock
file, setup lock DB, start level)
2.9 - ActiveMq (how to configure activeMq, create network of brokers,
pure master/slave, shared system lock, ...)
2.10 - Security (Simple authentication mechanism, encrypt password,
authentication with DB, LDAP)
2.11 - Migrate from Smx3 to Smx4
2.12 - Logging (setup log4j, log4j with file rotation, ....)
Regards,
Charles M.
On 20/10/10 00:23, Gert Vanthienen wrote:
L.S.,
Now that the initial bits for the Scalate-based documentation project
have been created, I'd like to start adding more contents to it so we
can have something to show off in a few weeks when we get ServiceMix
4.3.0 out. I'm going to work on the build a bit more to get
everything building a bit more smoothly and allow generating some of
the obvious bits (like e.g. the toc file for the commands).
For the contents, I was thinking of creating a set of documents and
manuals to suit the different user needs:
1. a quickstart guide: a short document that takes new users on a
guided tour through ServiceMix to give them an idea what ServiceMix is
about - something like start the container, look at the console,
install a feature, deploy a simple camel route, install an example,...
2. a user's guide/manual: a more length document, that explains about
the different components in the ServiceMix stack in the order set by
http://servicemix.apache.org/SMX4/technology-selection-guidelines.html,
so we gradually introduce complexity and can explain what the
additional benefits/features of every layer are when we introduce it
-- this would largely cover the original table of contents we had in
the docbook-based project
3. (optionally) a separate JBI user's guide/manual: given the
discussion about the future of ServiceMix, we might want to consider
moving the information about JBI (MEPs, API, ...) and the JBI
components with all their options into a separate document -- the
contents in this section would be highly relevant for ServiceMix 3.x
users as well and if we add this content to #2, we might end up with a
lot of information in there
4. the Karaf manual - the build currently just includes the original
files and rebrands them to match the design of the rest of the docs.
We might be able to add more contents from other projects in the same
way in the future (e.g. by taking the input from Confluence and adding
that)
5. the Command Reference Guide - includes manual pages for all of the
console commands, not only the ones from Karaf itself, but we would
add the NMR, JBI, ODE, ... commands we include in our builds in here
as well
The main drawback of splitting out the contents over multiple
subdocuments would be that it's harder for people for find the right
information. For the website, we can probably add a custom google
search field to allow people to search a specific version's
documentation set. For the WAR file, we'll probably have to build
something like that ourselves with Lucene in the future, but it should
not be that hard with all the contents being in plain text files.
Once we agree on the overall organization of the contents, I'll start
creating the initial toc files for everything as well as create JIRAs
that correspond to these chapters/sections, so people can sign up for
writing one or more bits of the new documentation set.
Regards,
Gert Vanthienen
------------------------
Open Source SOA: http://fusesource.com
Blog: http://gertvanthienen.blogspot.com/
