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<[email protected]>wrote: >> >>> On Tue, Aug 16, 2011 at 11:06 AM, Emmanuel Lecharny<[email protected]> >>> 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
