[Gluster-devel] Gluster Programmers' Guide

[Vijay Bellur]

On 01/08/2014 07:54 PM, Jay Vyas wrote:
> - 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.

We have already selected markdown as the documentation system for 
GlusterFS. markdown is not very different from asciidoc and the last 
time I checked pandoc would not consider asciidoc as input and hence 
moved to markdown.

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

All of this is hosted in the doc/ directory of glusterfs repo [1].

-Vijay

[1] 
https://github.com/gluster/glusterfs/tree/master/doc/admin-guide/en-US/markdown
>
> 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
> <mailto:abperiasamy at gmail.com>> wrote:
>
>> On Tue, Jan 7, 2014 at 5:40 PM, Joe Julian <joe at julianfamily.org
>> <mailto:joe at julianfamily.org>> wrote:
>>
>>
>>     On 01/07/2014 05:37 PM, Emmanuel Dreyfus wrote:
>>
>>         Joe Julian <joe at julianfamily.org
>>         <mailto: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
>>         <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 <mailto:Gluster-devel at nongnu.org>
>> https://lists.nongnu.org/mailman/listinfo/gluster-devel
>
>
> _______________________________________________
> Gluster-devel mailing list
> Gluster-devel at nongnu.org
> https://lists.nongnu.org/mailman/listinfo/gluster-devel
>