[Gluster-devel] Gluster Programmers' Guide
Vijay Bellur
vbellur at redhat.com
Wed Jan 8 14:54:28 UTC 2014
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
>
More information about the Gluster-devel
mailing list