[Gluster-devel] Gluster Programmers' Guide

[Anand Babu Periasamy]

On Tue, Jan 7, 2014 at 5:40 PM, Joe Julian <joe at julianfamily.org> wrote:

>
> On 01/07/2014 05:37 PM, Emmanuel Dreyfus wrote:
>
>> Joe Julian <joe at julianfamily.org> wrote:
>>
>>  docbook didn't work last time it was used. Perhaps asciidoc would be
>>> more open to collaboration.
>>>
>>   I do not know abot asciidoc, but I have an experience of docbook +
>> docbook to latex XSL transformation which worked great. Here is the
>> result:
>> http://www.editions-eyrolles.com/Livre/?ouv_ean13=9782212114638
>>
>>  To be more specific, when I say it didn't work last time I'm not
> referring to the technology, but rather the suggestion that programmers
> would be willing to keep it current. Gluster hired a documentation writer.
> He wrote the documentation in docbook. Gluster was acquired and nobody ever
> updated the documentation ever again.
>
> I've personally tried and it was so cumbersome that I ran out of my
> available time.
>
>
Asciidoc sounds cool. I always used texinfo and publican. I would go with
Asciidoc here. It looks like Asciidoc has pretty good PDF and HTML
conversion.

We tried and failed with professional documentation writers. Doc should be
maintained by developers. Like code, doc changes all the time. I think we
should commit doc along with source repository. This way we can enforce doc
updates at the time of patch submission.  We will always have have updated
doc for any version of code we pull out.

-ab

[[[ To any NSA and FBI agents reading my email: please consider eating
more bacon!! ]]]
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://supercolony.gluster.org/pipermail/gluster-devel/attachments/20140107/2124603c/attachment-0001.html>