On 03/05/2013 09:43 AM, harry mangalam wrote:
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 <[email protected]> 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.
I've started to look at converting the admin guide to asciidoc so it'll
be easier to contribute to. I've also talked (briefly) about splitting
the documentation away from the release source to make contributing
easier. I plan on putting it up on github after I make at least enough
progress to make it obvious where it's heading.
_______________________________________________
Gluster-users mailing list
[email protected]
http://supercolony.gluster.org/mailman/listinfo/gluster-users
