Re: [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 <address@hidden
> <mailto:address@hidden>> wrote:
>
> > On Tue, Jan 7, 2014 at 5:40 PM, Joe Julian <address@hidden
> > <mailto:address@hidden>> wrote:
> >
> >
> >     On 01/07/2014 05:37 PM, Emmanuel Dreyfus wrote:
> >
> >         Joe Julian <address@hidden
> >         <mailto: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
> >         <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
> > address@hidden <mailto:address@hidden>
> > https://lists.nongnu.org/mailman/listinfo/gluster-devel
>
>
> _______________________________________________
> Gluster-devel mailing list
> address@hidden
> https://lists.nongnu.org/mailman/listinfo/gluster-devel