directory-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Stefan Seelmann <m...@stefan-seelmann.de>
Subject Re: Documentation system
Date Sun, 14 Oct 2012 15:03:53 GMT
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


Mime
View raw message