Re: [Gluster-devel] Gluster Programmers' Guide

[Anand Babu Periasamy]

On Tue, Jan 7, 2014 at 5:40 PM, Joe Julian <address@hidden> wrote:

On 01/07/2014 05:37 PM, Emmanuel Dreyfus wrote:

Joe Julian <address@hidden> 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!! ]]]