On 10.10.2012 16:42, Pierre-Arnaud Marcelot wrote: >> I wanted to ask about the documentation system. Some time ago there was >> agreement to use version controlled files with wiki synatx that is >> transformed to docbook and then further transformed to HTML/PDF. Is this >> still the case or did something change? > > Nothing changed at the moment, but I think it raises the question of a switch > to Markdown on that part of the documentation too. > Maybe it's better if we share the same syntax between the website and the > documentation systems.
I agree that using Markdown for the documentation makes sense. Convertion should be straigh forward. However the currently used toolchain (especially Eclipse Mylyn WikiText which is used for editing and for converting wiki syntax to docbook within the maven build) does not support markdown [1]. >> I ask also wrt to the ongoing >> migration of the website to the Apache CMS: when using the CMS is it >> still possible to add static content (i.e. the generated documentation) >> to the website? > > Yeah, this is supported by the Apache CMS. > The static content can be added directly in subversion or it can be > compressed into an archive and imported via the online Apache CMS, see [1] Thanks for the pointers, Pierre-Arnaud. Anyway, even it is possible I still wonder if we should continue with the current system (Maven project in SVN, edited at local computer, documents generated via Maven build) or if we should move the content to the CMS. Let me just write down some pros/cons of each system here, they descirbe my current POV, please correct me if I'm wrong and add additional arguments. Pros of current system: * HTML and PDF output * Thanks to DocBook a TOC and navigation links are generated * Probably easiser to handle different versions (ApacheDS 2.0, 2.1, 3.0) using branches and merge changes between branches (but do we really do that?) Cons of current system: * Changes are not immediately visible on the website * Separate steps required to publish the HTML to the website * Layout of HTML output does not look exactly like the website layout Pros of CMS solution: * Changes are immediately visible * Easier usage and patch creation for non-committers [2] * Editing in webbrowser or offline Cons of CMS solution: * No PDF generation OOTB, but it should be possible to use the CMS folder as source, but needs some work Kind Regards, Stefan [1] https://bugs.eclipse.org/bugs/show_bug.cgi?id=329528 [2] http://www.apache.org/dev/cmsref.html#non-committer
