L.S., Awesome work, Jean-Baptiste and Charles! I've been looking at Docbook as a way for improving our documentation as well, you'll find my initial stab at https://svn.apache.org/repos/asf/servicemix/sandbox/gertv/documentation/trunk/. As you mention yourselves, the real benefit of using this kind of format for generating the documentation is the fact that we can manage multiple versions of it. The syntax itself is extremely verbose compared to what we do now with the wiki and it might be more difficult for people to contribute docs. On the other hand, using svn does allow for documentation patches, something we can't do right now. So I guess we have to look into the benefits/drawbacks for both approaches. We probably want to use a mix of both (e.g. Docbook for reference materials and manuals and the wiki for FAQs, tips and tricks, ...)
If we go for the Docbook based approach, I would propose to create a separate module in subversion to hold the documentation rather than include it with the project sources themselves. Especially in the beginning, the documentation will keep on changing/improving even after releases have been tagged for the projects. Also, if we think this through carefully, we can probably use svnmerge or something to make it easier to maintain the different version of the documentation. In order to get things in there more quickly, I was planning to add another goal to the documentation tooling plugin to pull in confluence pages and transform them to the new syntax. While I was tinkering with the documentation stuff, I also took a stab at a new website front page in https://svn.apache.org/repos/asf/servicemix/sandbox/gertv/website/trunk/ with a slightly (improved?) design for the header/footer. The goal of the new front page proposal is to make it as easy as possible for people to get started and find their way to the docs and downloads. Once we have released ServiceMix 4.2.0, I think we should direct people to that version for download by default. We can add a part on the download page that refers to the pure JBI 3.3.x line for our existing users, but I would like to avoid the confusion for people that are new to ServiceMix. Disclaimer: I'm not a graphics artist nor a web designer, so please consider this more of a proof-of-concept example then a definitive design. Regards, Gert Vanthienen ------------------------ Open Source SOA: http://fusesource.com Blog: http://gertvanthienen.blogspot.com/ On 7 February 2010 21:44, Jean-Baptiste Onofré <[email protected]> wrote: > Hi all, > > Charles and I have made some progress on the documentation sandbox. > > You will find in attachment: > - SMX3 installation guide > - SMX4 manual > I attached only PDF output (but the documentation project can generate HTML, > etc). > > I think that the documentation should a subproject of each main project. For > example, SMX4 (containing mainly assembly of NMR, feature, specs, bundles, > etc) should include the SMX4 documentation. Like this, we can version > documentation matching the release. > > Any comments are welcome. > > The source is here: > https://svn.apache.org/repos/asf/servicemix/sandbox/jbonofre/documentation/ > > We continue progress on this. > > Big thanks to Charles. > > Regards > JB >
