[Gluster-users] Disappointing documentation?

[Brian Candler]

On Tue, Mar 05, 2013 at 08:33:28AM -0800, 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.

When people come to this list and say "I am seeing split brain errors" or
"ls shows question marks for file attributes" or "I need to replace a failed
server with a new one" or "probing a server fails", I don't think there's
any official documentation to help them.

"Documenting how to troubleshoot" would include what log messages you should
look for and what they mean, what xattrs you should expect to see on the
bricks and what they mean (for each case of distributed, replicated etc). 
Given a basic checklist of these things, it would be easy for users to
report to the list "I checked A, B and C and the output from B was XXXX when
the docs say it should be YYYY on a working system", which is at least a
starting point.

As far as I'm aware, the official admin guide is completely oblivious to
internals like this.

Users may be able to find suggestions by perusing mailing list archives, or
by trying gluster 2.x wiki documentation (which may be stale), or some blog
postings.