Re: [Gluster-devel] GlusterFS Documentation improvements

[Kaushal M]

On 30-Jul-2013 8:23 PM, "Vijay Bellur" <address@hidden> 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.
>
> 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 ;-).
>
> Regards,
> Vijay
>
>
>
>
>
> _______________________________________________
> Gluster-devel mailing list
> address@hidden
> https://lists.nongnu.org/mailman/listinfo/gluster-devel