Guillaume, I actually meant just separate directories as it is now - I don't see a good reason to make that separate projects, I was just hoping to coming up with a good way to split out the contents over a few well-defined sections so it's easier to find the file you want to edit and for users to find some information to suit their needs.
Regards, Gert Vanthienen ------------------------ Open Source SOA: http://fusesource.com Blog: http://gertvanthienen.blogspot.com/ On Wed, Oct 20, 2010 at 12:42 AM, Guillaume Nodet <[email protected]> wrote: > 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 >
