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/ >>>>> >>> >> >
