When you mean splitting over multiple sub-documents, do you imply using separate maven projects for that, or just a separate directory as it's done now?
On Wed, Oct 20, 2010 at 00:29, Eric Johnson <[email protected]>wrote: > I can help out doing some of the CSS work to get the look and feel right. > I'll create a few different looks and pass them around. > Cheers, > Eric > > On Tue, Oct 19, 2010 at 6:23 PM, Gert Vanthienen > <[email protected]>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/ > -- Cheers, Guillaume Nodet ------------------------ Blog: http://gnodet.blogspot.com/ ------------------------ Open Source SOA http://fusesource.com
