I hear ya Eric!
We just need to watch carefully that doing an svn external link will
still allow us to keep the material coherent. For example, we don't go
introducing a concept in SMX documentation, and then go reintroducing it
in the 'pulled-in' Karaf documentation! Care and nurture will be
required to get the balance right so that the incorporation of chapters
from Karaf is seamless.
/Ade
On 20/10/2010 12:37, Eric Johnson wrote:
You could use SVN external to import the contents of the Karaf docs into the
ServiceMix documentation. That would allow the Karaf docs to stay up to date
without needing to duplicate the work.
On Wed, Oct 20, 2010 at 6:50 AM, hans couder<[email protected]> wrote:
Hi,
Sounds like a good idea.
If you needs some doc writers, count me in :)
Regards,
Hans Couder
2010/10/20 Gert Vanthienen<[email protected]>:
L.S.,
In the current documentation project, the Karaf material is just
literally copied over into the documentation project, so we can give
it a unified look and feel and to allow us to cross-link between the
documents even when it is deployed as a WAR file on top of ServiceMix
itself. I do agree with Guillaume though that we should avoid
rewriting/restructuring it at our end. We'll just create additional
work for ourselves without actually adding to the contents.
If there are bits in the administrator's guide that are missing now,
we'd better add those to the Karaf docs instead. For the
NMR/Camel/JBI-specific configuration, I would suggest we add a chapter
about then when we discuss the actual technology itself.
Regards,
Gert Vanthienen
------------------------
Open Source SOA: http://fusesource.com
Blog: http://gertvanthienen.blogspot.com/
On Wed, Oct 20, 2010 at 9:15 AM, Adrian Trenaman<[email protected]>
wrote:
I would prefer that we do /not /attempt to embed the Karaf material
into a
ServiceMix documentation, for the reasons that Guillaume states below.
Instead, let's provide beefy Karaf users / dev / administrators guides,
and
then /reference /these documents from the ServiceMix materials.
Am I being too modular?
On 20/10/2010 07:31, Guillaume Nodet wrote:
I don't have much problem with ah admin guide, but I don't think
rewrite
the
karf doc is a good idea. So anything we do should leverage the karaf
doc,
not rewrite it, else we duplicate the maintenance effort with all the
risks
of being out of sync.
On Wed, Oct 20, 2010 at 08:23, Charles
Moulliard<[email protected]>wrote:
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/
