[Gluster-devel] GlusterFS Documentation improvements

[Joe Julian]

By the way, pandoc does support asciidoc according to 
http://johnmacfarlane.net/pandoc/

On 07/30/2013 07:52 AM, Vijay Bellur 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.
>
>
> 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