[Gluster-users] Disappointing documentation?

[harry mangalam]

Mostly a Ditto on Shawn's piece.  Among the best format of documentation for a 
complex system like gluster is what was produced for MySQL a while ago.  I 
think it still exists:

http://dev.mysql.com/doc/refman/5.5/en/installing.html
(see comment at bottom)

Don't know what they use to do this, but it's pretty effective .

This allows user comments to be added directly to the docs, possibly verified 
or at least filtered by the doc manager, so that the comments and additional 
helpful links are available to people browsing the docs without having to go 
off to other sites (or at least it makes the other sites' relevant docs 
available from the mainline docs).  This consolidates all the info in one 
place.

Since all software is essentially a rolling beta, it makes sense for the docs 
to reflect that and leverage user comments into the main.

hjm



On Tuesday, March 05, 2013 12:33:18 PM Shawn Nock wrote:
> 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.

---
Harry Mangalam - Research Computing, OIT, Rm 225 MSTB, UC Irvine
[m/c 2225] / 92697 Google Voice Multiplexer: (949) 478-4487
415 South Circle View Dr, Irvine, CA, 92697 [shipping]
MSTB Lat/Long: (33.642025,-117.844414) (paste into Google Maps)
---
"Something must be done. [X] is something. Therefore, we must do it."
Bruce Schneier, on American response to just about anything.