gluster-devel
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [Gluster-devel] GlusterFS Documentation improvements


From: Vijay Bellur
Subject: Re: [Gluster-devel] GlusterFS Documentation improvements
Date: Tue, 30 Jul 2013 20:22:53 +0530
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:17.0) Gecko/20130514 Thunderbird/17.0.6

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






reply via email to

[Prev in Thread] Current Thread [Next in Thread]