[Gluster-users] Disappointing documentation?

[Toby Corkindale]

On 06/03/13 03:33, Joe Julian wrote:
> It comes up on this list from time to time that there's not sufficient
> documentation on troubleshooting. I assume that's what some people mean
> when they refer to disappointing documentation as the current
> documentation is far more detailed and useful than it was 3 years ago
> when I got started. I'm not really sure what's being asked for here, nor
> am I sure how one would document how to troubleshoot. In my mind, if
> there's a trouble that can be documented with a clear path to
> resolution, then a bug report should be filed and that should be fixed.
> Any other cases that cannot be coded for require human intervention and
> are already documented.
>
> Please tell me your thoughts.

So I've asked things like this and received no help:
http://www.gluster.org/pipermail/gluster-users/2012-June/033398.html

I've found answers relating to old versions of glusterfs and asked if 
they still apply, to no response:
http://www.gluster.org/pipermail/gluster-users/2012-June/033478.html

I've seen other people ask about split-brain issues to no response:
http://thr3ads.net/gluster-users/2012/06/1962160-managing-split-brain-in-3.3


I've tried to figure things out about the self-heal daemon, and found no 
documentation (but at least received some responses on list):
http://thr3ads.net/gluster-users/2012/05/1919111-3.3-beta3-When-should-the-self-heal-daemon-be-triggered


I found that the official documentation for the 3.2->3.3 upgrade path 
was in fact erroneous and did not work:
http://www.mail-archive.com/gluster-users@gluster.org/msg10890.html
(This turned out to be because the blog the wiki had copied the commands 
from had turned hypens into mdashes)


I've gone looking for info on the options available to simply mounting a 
glusterfs volume, and would you believe the latest version available 
with docs on the website is 3.2, not 3.3? (At least as far as a google 
search is concerned):
https://www.google.com.au/search?q=glusterfs+mount+volume



So, yeah, from my point of view GlusterFS's documentation fails at 
covering (a) simple, day-to-day actions, (b) upgrade paths, (c) handling 
failures.


I note there is also this site:
http://community.gluster.org/t/glusterfs/

It's full of people asking questions, and almost completely empty of 
people receiving useful replies. I know it's a *community* driven thing, 
but still.. it doesn't keep a good impression of community support.



The mailing list is often a source of good, useful information, and I 
appreciate everyone's help. Thanks for continuing to provide that support!
It would just be great if some of the collective's knowledge was 
available online in an easily-searched manner, and kept up to date.

Cheers,
Toby