directory-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Emmanuel Lecharny <elecha...@gmail.com>
Subject Re: ApacheDS documentation: docbook vs. wiki syntax
Date Tue, 18 Oct 2011 21:22:23 GMT
Hi,

On 9/18/11 10:20 PM, Stefan Seelmann wrote:
> Hi guys,
>
> I'd like to come back to our documentation issue:
> - docu in confluence isn't versionized
> - docbook in source control isn't easy to write
>
> I did some research and found some interesting links [1][2][3]. I
> setup an additonal user guide as PoC [4].
>
> The idea is as follows:
> 1. Documenation source is still stored in source control.
> 2. We use wiki syntax (confluence) to edit the documenation. Eclipse
> Mylyn WikiText includes editors for various wiki syntaxes (e.g.
> confluence, but not markdown) that provide content assist, syntax
> highlighting and a nice preview, see "Getting Started" of [1].
> 3. The wiki syntax is transformed to docbook xml. Unfortunately the
> required Mylyn libraries are not available in public maven repo and
> there is no maven plugin*. So I worked around and added the two
> required jars to the lib folder and added a maven-antrun-plugin
> execution to the POM.
> 4. Docbook is transformed to HTML, PDF, whatever
>
> I think that is a good way to make docu editing easier but still use
> the power of docbook to create different output formats. Of course not
> all features of docbook can be used but I think that is a minor issue.
> A bigger task is the transformation of the existing docbook files to
> confluence syntax.
>
> Looking forward to your feedback.

So I checked the project and the tools today : excellent !

We will now need to move all the wiki pages to svn. I will start with 
the API doco.

I suggest we create sub-project under documentation, one per project :
- ApacheDS (apacheds-manuals)
- Studio (studio-manuals : to be created)
- API (api-manuals : to be created)

Thoughts ?

-- 
Regards,
Cordialement,
Emmanuel L├ęcharny
www.iktek.com


Mime
View raw message