[Gluster-devel] Gluster Programmers' Guide

[Jay Vyas]

- So I guess we are all for asciidoc or any other "developer" oriented documentation system.  Sounds good. When you folks pick one Just let us know.

- Point us to the repo and we can all start contributing .

This Probably will simplify things for all of us because we won't have the wiki-rot problem anymore. 

Again I really like how this worked in the hbase community: hbase is a big program like gluster with similar need for diverse and ever evolving docs... And the code integrated docs really work well, and I think gluster is definetly ready for the same doc integration.



> On Jan 7, 2014, at 10:14 PM, Anand Babu Periasamy <abperiasamy at gmail.com> wrote:
> 
>> 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!! ]]]
> _______________________________________________
> Gluster-devel mailing list
> Gluster-devel at nongnu.org
> https://lists.nongnu.org/mailman/listinfo/gluster-devel
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://supercolony.gluster.org/pipermail/gluster-devel/attachments/20140108/2a8a7b89/attachment-0001.html>