[Gluster-devel] GlusterFS Documentation improvements

[Vijay Bellur]

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