+1. I agree on JB remark, the goal to have a manual is to generate HTML/pdf documents who will be part of the SMX/Karaf distribution.
To convert wiki (confluence) to docbook, there is a confluence plugin : http://confluence.atlassian.com/display/CONFEXT/Confdoc+DocBook+Converter For all of you which are a bit reluctant to code in XML the documentation, WYSIWYG editor exists --> http://wiki.docbook.org/topic/DocBookAuthoringTools ;-) Regards, Charles Moulliard Senior Enterprise Architect Apache Camel Committer ***************************** blog : http://cmoulliard.blogspot.com twitter : http://twitter.com/cmoulliard Linkedlin : http://www.linkedin.com/in/charlesmoulliard Apache Camel Group : http://www.linkedin.com/groups?home=&gid=2447439&trk=anet_ug_hm On Fri, Nov 20, 2009 at 9:34 AM, Jean-Baptiste Onofré <[email protected]> wrote: > Hi Gert, > > concerning the homepage, I'm agree to simplify this page. The OpenOffice.org > homepage is clean and easy to use. I think that we need to distinguish two > kinds of people on ServiceMix: > - the users who looking for the documentation (SMX manual), the distribution > and support( help/bugs tracking) > - the power users/developers who looking for a deeper documentation > (architecture manual), some contribution guide, etc > So displaying link to this topics directly is clean on the homepage (like > OpenOffice.org does). > > Concerning the documentation, from my point of view, the wiki should be > reserved for documentation not in the manual. > The manual targets are user. So the wiki can contain advanced documentation > (architecture, advanced topic) and could be referenced by the manual. > I think that the manual should be considered as a project itself, with > sources (DocBook files), versionning, etc. > Concerning the "easy" edit, I need to test if confluence is not able to > provide a DocBook file from a wiki page (it can imports from DocBook, so > maybe it can extract :)). In this case, the DocBook source can be hosted on > the wiki, gathered by the maven plugin to generate the target outputs . This > cinematic is used for the Camel manual using Prince. > > Regards > JB > > Gert Vanthienen wrote: >> >> L.S., >> >> Yeah, I also think our current home pages are a bit 'crowded' with too >> many links and just confusing new users on where they should go to get >> started. Personally, I would love to see a home page like the ones >> http://www.openoffice.org or http://rubyonrails.org are having, with a >> few very obvious links to get people going. If we could have that >> low-barrier landing page together with the improved, in depth >> documentation we're going for with the docbook/wiki combo, that would >> be a real asset to this project. >> >> For the docbook/wiki dilemma, that's a hard one. Obviously, using >> something like docbook to generate the documentation web pages, pdf >> documents, ... would offer some advantages: it would probably be >> easier to integrate pages from all kinds of places (felix karaf, >> camel, components, nmr, ...) to get everything a user needs nicely in >> one place. Another benefit would be the fact that the documentation >> itself is versionable too, so we no longer have documentation for all >> versions together. However, I also really like the easy-to-edit >> documentation we now have with the wiki. Not sure what the ideal >> solution would be here, something where we edit pages in the wiki and >> then extract/aggregate them with docbook and have some options to add >> generated docs for the components and their xml schema's? >> >> Regards, >> >> Gert Vanthienen >> ------------------------ >> Open Source SOA: http://fusesource.com >> Blog: http://gertvanthienen.blogspot.com/ >> >> >> >> 2009/11/19 Chris Custine <[email protected]>: >>> >>> I really like the proposed Home Page as well. I agree with Jamie that we >>> should flatten out ServiceMix 3 and 4 in the navigation column a bit. To >>> take his suggestions even further, I propose that we have ServiceMix 3 >>> and >>> ServiceMix 4 as their own top level menu items, with sub-items for >>> documentation, downloads, source, etc. For ServiceMix 4, I am thinking >>> the >>> Features, NMR and Kernel variations should be de-emphasized slightly by >>> just >>> referring to Features as ServiceMix 4. This is what most people think of >>> as >>> ServiceMix 4 anyway. We could differentiate between them on the >>> ServiceMix >>> 4 main page once the user gets there. >>> >>> I think the main page has been confusing for a while so I think this is a >>> great time to dig in and revise it a bit before we release the 3.x >>> updates, >>> 4.1, and the new components releases. I think flattening things out to >>> be a >>> bit more concise on the main page will help a lot of people navigate the >>> sire and understand the differences between SMX3 and 4. >>> >>> I'll be happy to spend a couple of days reviewing and making these >>> updates >>> if everyone generally agrees on this. >>> -- >>> Chris Custine >>> FUSESource :: http://fusesource.com >>> My Blog :: http://blog.organicelement.com >>> Apache ServiceMix :: http://servicemix.apache.org >>> Apache Directory Server :: http://directory.apache.org >>> >>> >>> On Thu, Nov 19, 2009 at 7:02 AM, Jamie G. <[email protected]> >>> wrote: >>> >>>> I really like the new home page design :) >>>> >>>> The only part that I could see a small improvement is in the >>>> 'Community' side panel. Specifically the three entries; Servicemix >>>> 4.0, Servicemix Kernel, and Servicemix NMR. Could we reorganize these >>>> into: >>>> >>>> Servicemix 3 (linked to >>>> http://servicemix.apache.org/getting-started.html) >>>> Servicemix 4 Features (linked to >>>> http://servicemix.apache.org/SMX4/index.html) >>>> Servicemix 4 NMR (linked >>>> tohttp://servicemix.apache.org/SMX4NMR/index.html) >>>> Servicemix 4 Kernel (linked to >>>> http://felix.apache.org/site/apache-felix-karaf.html) >>>> Servicemix Components (linked to >>>> http://servicemix.apache.org/components-list.html) >>>> >>>> This would help let new users quickly identify the different projects >>>> under Servicemix and to which version(s) they belong. >>>> >>>> Cheers, >>>> J >>>> >>>> On Thu, Nov 19, 2009 at 5:23 AM, Jean-Baptiste Onofré <[email protected]> >>>> wrote: >>>>> >>>>> Yes why not. It can be a step two in the documentation project. >>>>> >>>>> From my point of view, the purpose of wiki -> DocBook is to avoid to >>>> >>>> rewrite >>>>> >>>>> all the content. >>>>> >>>>> After we have two ways: >>>>> 1/ the wiki is the master and the documentation is generated from >>>>> there: >>>> >>>> the >>>>> >>>>> advantage is that it's simple to edit and provide but I'm not sure that >>>> >>>> the >>>>> >>>>> generated documentation will be very fine >>>>> 2/ the wiki pages will be deprecated and the sources are "static". >>>>> >>>>> Regards >>>>> JB >>>>> >>>>> Charles Moulliard wrote: >>>>>> >>>>>> That's perfect for me. >>>>>> >>>>>> Probably that we will need also a command to transform docbook into >>>>>> HTML page of wiki in order to synchronise docBook with Wiki in a >>>>>> symetric way. >>>>>> >>>>>> I don't know if this is interesting but there is a confluence docbook >>>>>> converter plugin : >>>>>> >>>> >>>> http://confluence.atlassian.com/display/CONFEXT/Confdoc+DocBook+Converter >>>>>> >>>>>> Regards, >>>>>> >>>>>> Charles Moulliard >>>>>> Senior Enterprise Architect >>>>>> Apache Camel Committer >>>>>> >>>>>> ***************************** >>>>>> blog : http://cmoulliard.blogspot.com >>>>>> twitter : http://twitter.com/cmoulliard >>>>>> Linkedlin : http://www.linkedin.com/in/charlesmoulliard >>>>>> >>>>>> Apache Camel Group : >>>>>> http://www.linkedin.com/groups?home=&gid=2447439&trk=anet_ug_hm >>>>>> >>>>>> >>>>>> >>>>>> On Thu, Nov 19, 2009 at 9:37 AM, Jean-Baptiste Onofré >>>>>> <[email protected]> >>>>>> wrote: >>>>>>> >>>>>>> Hi all, >>>>>>> >>>>>>> FYI, I have begun to write a maven plugin (in my sandbox repo) to: >>>>>>> - transform a DocBook documentations into HTML, FO, PDF >>>>>>> - be able to get confluence wiki HTML source, apply JTidy on it to >>>>>>> transform >>>>>>> into XHTML and apply a XSL to go to DocBook. >>>>>>> >>>>>>> This plugin will be used to generate the ServiceMix manual from >>>> >>>> provided >>>>>>> >>>>>>> DocBook document and to init these documents from the wiki. >>>>>>> >>>>>>> I would like to resume the work on the manual and, in the same of the >>>>>>> first >>>>>>> manual release, promotes http://servicemix.apache.org/home2.html to >>>> >>>> give >>>>>>> >>>>>>> more visibility. >>>>>>> >>>>>>> What do you think about this ? >>>>>>> >>>>>>> Thanks >>>>>>> Regards >>>>>>> JB >>>>>>> >>>>> -- >>>>> Jean-Baptiste Onofré (Nanthrax) >>>>> BuildProcess/AutoDeploy Project Leader >>>>> http://buildprocess.sourceforge.net >>>>> [email protected] >>>>> PGP : 17D4F086 >>>>> >
