I would like to volunteer in this effort. >From this Monday I will have some free cycles and I feel my fingers itching, so you can count me in.
On Wed, Oct 20, 2010 at 3:14 PM, Gert Vanthienen <[email protected]>wrote: > L.S., > > The current approach is to use the Karaf doc snapshot war and extract > the information from there, which boils down to the same thing but > does not rely on svn:externals (so it's easier to use with e.g. the > git mirrors we have for this). > > My plan was to just include the Karaf documentation as is, without > trying to do anything about integrating it in the other bits. I can > imagine we'll have to duplicate some bits (e.g. the quickstart guide > will have a short section on how to start the container as well), but > if we focus on the value added by ServiceMix (Camel, CXF, JBI, > ActiveMQ, ...) in our own manuals, we shouldn't have that much > overlap. We can always come back to the dev list and examine things > more closely if we discover there's too much overlap. > > I think we should leave it up to the ServiceMix book to provide the > nicely edited and integrated text about the entire ServiceMix stack. > For the documentation and the website, I'd more than happy if we get a > consistently looking set of manual and reference pages that allows > people to easily find what they're looking for. > > One of the main questions for sending this mail to dev list is still > open in my mind though: do we want to move the information about JBI > into a separate section/guide or keep it together with the rest of > contents? Personally, thinking about what we talked about in the > ServiceMix future thread, I'd prefer to move it into its own section, > so we can slowly guide people towards Camel, ActiveMQ, CXF, ... and > whatever we decide to add the ServiceMix platform in the future > without completely dropping JBI (we want evolution here, not an > anti-JBI revolution). However, I'd love to hear how everyone else > feels about this before I rush off and start moving pages in the > documentation project trunk. > > Regards, > > Gert Vanthienen > ------------------------ > Open Source SOA: http://fusesource.com > Blog: http://gertvanthienen.blogspot.com/ > > > > On Wed, Oct 20, 2010 at 1:41 PM, Adrian Trenaman <[email protected]> > wrote: > > 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/ > >>>>>>>> > >> > >> > > > -- *Ioannis Canellos* http://iocanel.blogspot.com Integration Engineer @ Upstream S.A. <http://www.upstreamsystems.com>
