directory-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Pierre-Arnaud Marcelot ...@marcelot.net>
Subject Re: Documentation system
Date Mon, 22 Oct 2012 10:16:09 GMT
Hi Stefan,

On 14 oct. 2012, at 17:03, Stefan Seelmann <mail@stefan-seelmann.de> wrote:

> 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].

Indeed. :-(

However, I personally do the documentation work outside of Eclipse using:
- BBEdit as text editor with markdown syntax highlighting
- Marked as a Markdown visualizator
- command line to generate the website locally before committing modifications

>>> 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.

I wonder too.

> 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?)

The current system should also allow us to automatically include the documentation in other
Maven projects.

We could, for example, include the ApacheDS user guide as HTML and/or PDF within the release
of ApacheDS itself.
Same thing for Studio and the LDAP API.

> 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

The layout can certainly be updated to look almost similar, so I'm not sure it's really an
issue.

I would add one more item to the current system's cons:
* Different syntax being used to edit the website and documentation files

> 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

Same thing for automation and re-usability of the documentation in other Maven projects.


The choice between the two systems isn't really easy.
Maybe we should try to create a utility to generate a PDF from markdown text.
I've seen some project which can convert from Markdown text to DocBook format.
Maybe it could be a solution.

Regards,
Pierre-Arnaud

> 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