[Gluster-devel] GlusterFS Documentation improvements

Kaushal M kshlmster at gmail.com
Tue Jul 30 19:06:14 UTC 2013


On 30-Jul-2013 8:23 PM, "Vijay Bellur" <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.
>
> 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
> Gluster-devel at nongnu.org
> https://lists.nongnu.org/mailman/listinfo/gluster-devel
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://supercolony.gluster.org/pipermail/gluster-devel/attachments/20130731/423669ff/attachment-0001.html>


More information about the Gluster-devel mailing list