[Gluster-users] Disappointing documentation?

[Shawn Nock]

Joe Julian <joe at julianfamily.org> writes:

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

It is true that the documentation has gotten better. 

However, since the switch to the new release cycle, bugs don't seem to
get fixed (within a release) and the documentation could do a better job
listing some of the holes new users starting with the current GA will
likely fall into:

Examples:

- Don't use ext4
(https://bugzilla.redhat.com/show_bug.cgi?id=838784)

- Don't use fix-layout after adding a brick
(https://bugzilla.redhat.com/show_bug.cgi?id=913699), maybe fixed by
10617e6cbc73329f259b471327d88375352042b0 in 3.3.1 but:

- Don't upgrade from 3.3 to 3.3.1 if you need NFS 
(https://bugzilla.redhat.com/show_bug.cgi?id=893778)

1. Perhaps a wiki entry like "Known Issues" with links to all these bugs?

2. Copying the excellent info about gluster's xattrs from this blog
post (http://cloudfs.org/2011/04/glusterfs-extended-attributes/) into
the admin guide would be a start.

3. A brief guide on how to collect info on problematic files
(permissions, xattrs, client log, brick log) would probably help generate
more helpful bug reports and help users sort out many of their own
problems.

It's all stuff you pickup after you've been in the game for a while, but
they must really flummox new users.

-- 
Shawn Nock (OpenPGP: 0x65118FA5)
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 835 bytes
Desc: not available
URL: <http://supercolony.gluster.org/pipermail/gluster-users/attachments/20130305/63e1f674/attachment.sig>