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>
