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/ > >>>>> > >>> > >> > > > -- Principle Technical Writer Phone (781) 280-4174 Skype finnmccumial E-Mail [email protected] Blog http://documentingit.blogspot.com/
