[Gluster-users] Disappointing documentation?

[Joe Julian]

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