<p dir="ltr"><br>
On 30-Jul-2013 8:23 PM, "Vijay Bellur" <<a href="mailto:vbellur@redhat.com">vbellur@redhat.com</a>> wrote:<br>
><br>
> On 07/30/2013 06:56 PM, Lubomir Rintel wrote:<br>
>><br>
>> Hello everyone,<br>
>><br>
>> I've found GlusterFS documentation hard to follow. I've often found<br>
>> resources useful to me only by accident, scattered across the wiki, in<br>
>> source tree, blogs or presentation slides. Lots of documents were on<br>
>> the other hand inaccurate or incomplete, maybe just because GlusterFS<br>
>> development progressed making them obsolete. The more I got involved<br>
>> with GlusterFS use, the more I wished for a consistent guide/book I<br>
>> could follow to grasp understanding of ideas behind its architecture<br>
>> as well as implementation.<br>
><br>
><br>
> +1. A lot of information is scattered and there is no good mechanism to integrate the useful stuff and leave out the noise.<br>
><br>
><br>
>><br>
>> I would very much like to help improve the situation (as time would permit).<br>
>><br>
>> I'm not sure how, though, and need some help with that. What I'd like<br>
>> to avoid is clashing with anyone's else work, or preparing patches<br>
>> that would get immediately refused. I've prepared an short analysis of<br>
>> current documentation and overview of what would changes make sense to<br>
>> me:<br>
>><br>
>> <a href="https://github.com/lkundrak/glusterfs/wiki/Documentation-improvement-ideas">https://github.com/lkundrak/glusterfs/wiki/Documentation-improvement-ideas</a><br>
>><br>
>> I'd be very thankful for feedback, especially from people that are<br>
>> working on documentation currently, have plans about changes to it or<br>
>> are familiar with history behind current situation. "This does not<br>
>> make any sense," or "Go ahead, do this!" would definitely be<br>
>> appreciated.<br>
>><br>
><br>
> I will try to provide a section-wise feedback of your doc on where we stand today and what can be done.<br>
><br>
> General ideas:<br>
><br>
> 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.<br>
><br>
> 2. A well structured doc/ folder to be the container for all documentation.<br>
><br>
> 3. Adding a developer/hacking section in addition to admin-guide would be nice to have.<br>
><br>
> Admin Guide:<br>
><br>
> 1. All in markdown. Need to evolve a process to roll down the latest admin guide on to <a href="http://gluster.org">gluster.org</a>.<br>
><br>
> 2. 3.1.x and 3.2.x documentation is relevant for the respective releases.<br>
><br>
> 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.<br>
><br>
> User Guide:<br>
><br>
> 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.<br>
><br>
><br>
> Hacking GlusterFS:<br>
><br>
> 1. Most individual files not up to date. Concur that it would be good to make it current and convert this to markdown.<br>
><br>
> 2. Even the development work flow can be converted to a markdown document.<br>
><br>
> 3. The Arch and Presentation sections can be made more accessible in the website.<br>
><br>
> Translator reference:<br>
><br>
> 1. legacy references can be removed.<br>
><br>
> 2. <a href="http://gluster.org/community/documentation/index.php/Gluster_Translators">http://gluster.org/community/documentation/index.php/Gluster_Translators</a> - looks mostly random, a better table can be generated from the o/p of "volume set help" and/or from code.<br>
><br>
> 3. <a href="http://gluster.org/community/documentation/index.php/Translators">http://gluster.org/community/documentation/index.php/Translators</a> - incomplete, but might be a good starting point.<br>
><br>
> 4. More information on translators can be part of the developer<br>
><br>
> volfiles:<br>
><br>
> can be git rm -rf'ed<br>
><br>
> Random:<br>
><br>
> 1. All legacy stuff can be git rm -rf 'ed<br>
><br>
> 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.<br>
><br>
> 3. doc/glusterd.vol is packaged. Can probably move to extras.<br>
><br>
> Manual Pages:<br>
><br>
> To be cleaned up and brought up to date.<br>
><br>
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).<br>
Since, pandoc supports generation of man pages from markdown, if do this conversion it'll be easier to maintain them.</p>
<p dir="ltr">~kaushal <br>
><br>
> 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 ;-).<br>
><br>
> Regards,<br>
> Vijay<br>
><br>
><br>
><br>
><br>
><br>
> _______________________________________________<br>
> Gluster-devel mailing list<br>
> <a href="mailto:Gluster-devel@nongnu.org">Gluster-devel@nongnu.org</a><br>
> <a href="https://lists.nongnu.org/mailman/listinfo/gluster-devel">https://lists.nongnu.org/mailman/listinfo/gluster-devel</a><br>
</p>