[Gluster-users] Disappointing documentation?

[Joe Julian]

On 03/05/2013 05:12 PM, Toby Corkindale wrote:
> 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

Not intending to excuse the lack of response, but I know I was on 
vacation at that time. June 7th was a Friday and I've noticed that 
Fridays in general are sub-optimal for finding support on things.

I'll also freely admit that I despise doing support over email. That 
question was open-ended and actually requires a very long response, of 
which I suppose everyone felt overwhelmed and wanted to get home and 
have a beer. I know for me, one problem I have with email support is 
that once my train of thought has derailed, I'm loath to get it on track 
again.

I don't suppose you tried the IRC channel? There's usually someone there 
that is willing to walk people through just about anything.

>
> 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 
>

There are several responses there.

>
>
> 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 
>

Definitely hard to get support on beta or qa releases. Probably because 
everyone's still in the process of testing. When anything is that young, 
there's a very small knowledge pool. Normally there are a lot of bugs 
found during the qa and beta releases and the people best suited to 
answering those questions are busy squashing them.

Does anybody have any thoughts on how that problem could be mitigated?

>
> 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)

Yes, I remember that discovery. It wasn't like that when it was 
originally posted but there was a drastic circumstance that required 
exporting and importing. It should have been on the wiki though. Bad 
Vijay... ;)

>
> 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

I don't believe the mount options changed from 3.2. I was aware that 
someone made the decision that the 3.2 documentation was "still current" 
for 3.3 but I don't recall who said that. (JMW?)

That goes back to what I was saying about converting from Publican. It's 
far too cumbersome to contribute to.

>
> 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'll disagree on the "simple day-to-day" actions. Healing split-brain is 
neither simple, nor should it be day-to-day. The simple actions are 
covered. And, frankly, the only day-to-day operations that are commonly 
done are scouring logs and monitoring systems. The rest of the simple 
operations generally happen rarely but for fixed conditions.

>
> 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.
>

99% of the "questions" are statements and the quality of the questions 
are so bad that I got so frustrated that I stopped looking at them. Top 
that with people posing additional questions as answers and my ocd 
tendencies finalized that decision. Yes, it's probably irrational that 
it makes me so angry that people don't even know the difference between 
a question and an answer, but that's my problem. :/

>
> 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.

Again I agree and ask that if you know something, publish it. The wiki's 
available, there's any number of blogging sources. Email it to the list, 
etc.

Anybody can create an account on the wiki and add/edit. Please do. Maybe 
even go through the mailing list backlogs and glean information from 
there to put on the wiki. Copy and paste my own blog (I keep meaning to 
rewrite my posts to fit wiki docs and formatting, but that hasn't been 
very high on my priority list).

Also, the IRC channel is another valid resource. I'm almost always 
online there if I'm near a computer, as are many other competent, 
friendly people who can usually walk you through any problem you might 
find - or at least walk you through identifying a bug and getting it filed.