[Gluster-devel] GlusterFS Documentation improvements

Tue Jul 30 22:11:48 UTC 2013

The docs (markdown version) are in doc/admin-guide/en-US/markdown for 
release-3.4 and master. I'd like to have these converted for 3.3 as well.

I started to automate the publication of the existing content but I 
noticed some deficiencies in order to make it happen. I need a title 
page that links to the chapters and the chapter files need to be renamed 
such that they can be ordered correctly when assembling a pdf or edoc, 
such as 01_admin_console.md, 02_admin_storage_pools.md, etc.

When I create the html version, I plan on stripping off the ##_ so the 
page names will be like admin_console.html

Thanks for getting involved in this. It's been something that I've 
wanted to do for a while.

On 07/30/2013 12:06 PM, Kaushal M wrote:
>
>
> On 30-Jul-2013 8:23 PM, "Vijay Bellur" <vbellur at redhat.com 
> <mailto:vbellur at redhat.com>> wrote:
> >
> > On 07/30/2013 06:56 PM, Lubomir Rintel wrote:
> >>
> >> Hello everyone,
> >>
> >> I've found GlusterFS documentation hard to follow. I've often found
> >> resources useful to me only by accident, scattered across the wiki, in
> >> source tree, blogs or presentation slides. Lots of documents were on
> >> the other hand inaccurate or incomplete, maybe just because GlusterFS
> >> development progressed making them obsolete. The more I got involved
> >> with GlusterFS use, the more I wished for a consistent guide/book I
> >> could follow to grasp understanding of ideas behind its architecture
> >> as well as implementation.
> >
> >
> > +1. A lot of information is scattered and there is no good mechanism 
> to integrate the useful stuff and leave out the noise.
> >
> >
> >>
> >> I would very much like to help improve the situation (as time would 
> permit).
> >>
> >> I'm not sure how, though, and need some help with that. What I'd like
> >> to avoid is clashing with anyone's else work, or preparing patches
> >> that would get immediately refused. I've prepared an short analysis of
> >> current documentation and overview of what would changes make sense to
> >> me:
> >>
> >> 
> https://github.com/lkundrak/glusterfs/wiki/Documentation-improvement-ideas
> >>
> >> I'd be very thankful for feedback, especially from people that are
> >> working on documentation currently, have plans about changes to it or
> >> are familiar with history behind current situation. "This does not
> >> make any sense," or "Go ahead, do this!" would definitely be
> >> appreciated.
> >>
> >
> > I will try to provide a section-wise feedback of your doc on where 
> we stand today and what can be done.
> >
> > General ideas:
> >
> > 1. Consistent format for documentation would be markdown. There are 
> some thoughts on moving to asciidoc but given limited asciidoc support 
> in pandoc, we can live with markdown for now.
> >
> > 2. A well structured doc/ folder to be the container for all 
> documentation.
> >
> > 3. Adding a developer/hacking section in addition to admin-guide 
> would be nice to have.
> >
> > Admin Guide:
> >
> > 1. All in markdown. Need to evolve a process to roll down the latest 
> admin guide on to gluster.org <http://gluster.org>.
> >
> > 2. 3.1.x and 3.2.x documentation is relevant for the respective 
> releases.
> >
> > 3. Basic_Gluster_Troubleshooting, GlusterFS_Concepts, QuickStart, 
> Getting_started_overview are not yet in the git repo. Might be good to 
> have them in markdown too.
> >
> > User Guide:
> >
> > Mostly legacy stuff, have not been touched in years. We can probably 
> clean them up from the repo if they cannot be easily massaged to 
> reflect the current state.
> >
> >
> > Hacking GlusterFS:
> >
> > 1. Most individual files not up to date. Concur that it would be 
> good to make it current and convert this to markdown.
> >
> > 2. Even the development work flow can be converted to a markdown 
> document.
> >
> > 3. The Arch and Presentation sections can be made more accessible in 
> the website.
> >
> > Translator reference:
> >
> > 1. legacy references can be removed.
> >
> > 2. 
> http://gluster.org/community/documentation/index.php/Gluster_Translators 
>  - looks mostly random, a better table can be generated from the o/p 
> of "volume set help" and/or from code.
> >
> > 3. http://gluster.org/community/documentation/index.php/Translators 
> - incomplete, but might be a good starting point.
> >
> > 4. More information on translators can be part of the developer
> >
> > volfiles:
> >
> > can be git rm -rf'ed
> >
> > Random:
> >
> > 1. All legacy stuff can be git rm -rf 'ed
> >
> > 2. features is a placeholder directory that we created to host 
> documentation on features. Can be moved to more appropriate locations 
> as part of the cleanup. All sources have to be in markdown.
> >
> > 3. doc/glusterd.vol is packaged. Can probably move to extras.
> >
> > Manual Pages:
> >
> > To be cleaned up and brought up to date.
> >
> Can we also try to move the man pages to markdown as well? I tried to 
> update them for the 3.3 release, but wasn't able to get much done 
> because the markup language used is hard to make sense of (at least 
> for me).
> Since, pandoc supports generation of man pages from markdown, if do 
> this conversion it'll be easier to maintain them.
>
> ~kaushal
> >
> > Thanks for your effort in putting this together. I am all for 
> getting documentation to a better place than where it is today and 
> given where we are, it might not be a very hard exercise initially ;-).
>

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://supercolony.gluster.org/pipermail/gluster-devel/attachments/20130730/05f30473/attachment-0001.html>