On 17 août 2011, at 11:47, Emmanuel Lecharny wrote:

On 8/17/11 11:12 AM, Alex Karasulu wrote:
On Wed, Aug 17, 2011 at 12:15 AM, Stefan Seelmann<seelmann@apache.org>wrote:

On Tue, Aug 16, 2011 at 11:06 AM, Emmanuel Lecharny<elecharny@gmail.com>
wrote:
Last, not least, we need to improve the kerberos documentation. Many
users
complain about it. The truth is that we fixed some blocking issues those
last weeks, bugs that were killing our implementation as a valid
candidate
for a production kerberos server. But bugs are bugs, we can fix them.
OTOH,
with a pathetic documentation, we can't expect to have users testing the
kerberos server, and giving us some feedback about problems they found in
the code. Sadly, we need some workforce to deal with this problem...
I totally agree with that point. I played with Kerberos the last weeks
so I see it as my duty to contribute some documentation. But I'm
unsure what documentation system we should use. Felix did a great job
and moved all confluence pages to Docbook. But I know that at least
you (sorry, I won't blame you ;-) don't like Docbook XML. So should we
switch back to confluence?


The nice thing about docbook is that always us to generate any target and
manipulate formats with style sheets. I think it's idea even though it's
heavy. We just need a nice tool that allows us to edit docbook in a WYSIWYG
editor. This way one need not deal with XML directly.

I spent hours finding such hypothetical tools, and tested many of them. They are all crap. really.

The fact that we need docbook format for our documentation is not disputed here. I just say that we'd rather use a standard way to produce the doco, then we convert it to docbook later, using a tool to do so.

I agree that writing documentation in Docbook is not that sexy and it needs a lot of XML-loving...
That said, with Stefan, we managed to get the whole Studio documentation in that format and the benefits were huge. :)
The only drawback of Docbook (which can be an advantage too, depending on the POV) is it's XML syntax which makes writing less easy.

I'm not sure we can really automate the conversion from a higher-level (and simpler) text format to the Docbook format which has its own concepts like chapters, sections, links between various parts, images insertion, etc.
But it has to be tested.

One interesting and simple workaround might be to use the Markdown language [1]. It's meant for very easy text editing and it's pretty close to what we're used to in Confluence. Have look a the syntax here [2].

On my side, I don't mind writing plain Docbook as I know the syntax and I'm pretty used to used to it now.
However if this other lighter format (or another one) can help less experienced Docbook writers, I'm totally fine with it.
We just need to verify that in the end the converted docbook looks good and works will all our needs (cross-section links, image and code insertion, etc).

Writing documentation is already complicated and something we're not very keen on doing... If things are even harder because of some crappy syntax, we will never get a decent documentation.

Regards,
Pierre-Arnaud  


[1] - http://daringfireball.net/projects/markdown/
[2] - http://daringfireball.net/projects/markdown/syntax