[Gluster-users] Meta-discussion

[Fred van Zwieten]

How about this:

"Reference Manual/Guide": This describes how to operate the product.
Describe all statements with all options, etc
"User Manual/Guide": This describes how to "use" the product in various use
cases. More of an architectural level.
"Operation Manual/Guide": This describes, in a cookbook style, how to
change/enhance/etc a current setup. Things like adding a server, growning a
volume, etc.
"Troubleshoot Manual/Guide": This describes the various troubleshooting
scenario's
"Developer Manual/Guide": This describes api's, programming examples using
various bindings, under the hood info, like xattr meanings, etc.

This can also be sections or chapters in a single manual..

Cheers,
Fred


On Wed, Jan 2, 2013 at 4:05 PM, Brian Candler <B.Candler at pobox.com> wrote:

> On Wed, Jan 02, 2013 at 09:03:59AM -0500, Jeff Darcy wrote:
> > * A general "principles of operation" guide - not a whole book, but more
> than
> > bits scattered among slide presentations and wiki pages.  Let's say
> something
> > that would be on the order of 15-50 pages printed out.
>
> Personally I'd like to see the details as well as principles. Take
> replication as an example: I'd want to know exactly what xattrs are written
> and when, what the values mean, what values are seen in intermediate
> states,
> on successful completion and when replication failed.  Ditto for
> distribution (DHT).
>
> Since these details may change with the code, I wouldn't mind if they sat
> in
> the git repo alongside the code itself.
>
> > * Many "cookbook" examples detailing initial configurations for common
> use
> > cases (e.g. media servers, VM storage) and higher-level sequences of
> steps for
> > common operations (e.g. adding servers).
>
> Not just "common" operations; I believe what's really important is the
> uncommon operations in failure scenarios.  e.g.  replacing a failed server;
> replacing a failed brick filesystem within a server; how to diagnose and
> fix
> problems with stuck replication and stuck rebalancing, or when the volume
> config is out of sync between peers (which bit me badly).
>
> I think Red Hat's documentation of LVM is a good example of how this can be
> done well:
>
>
> https://access.redhat.com/knowledge/docs/en-US/Red_Hat_Enterprise_Linux/6/html/Logical_Volume_Manager_Administration/
>
> Not only does it give how-to examples of pretty much everything you might
> want to do with LVM, it also has a whole section on troubleshooting tools
> and recovery procedures, and an appendix on low-level configuration of dm
> (analogous to the volfiles in gluster)
>
> Finally, although I realise that RH is aiming towards a storage appliance,
> I
> still think it would be useful to document how (safely) to manipulate the
> volfiles by hand and keep them in sync between peers - the custom
> translators are all still there and it would be good to be able to use
> them,
> and this is likely to encourage third-party feature development.
>
> Regards,
>
> Brian.
> _______________________________________________
> Gluster-users mailing list
> Gluster-users at gluster.org
> http://supercolony.gluster.org/mailman/listinfo/gluster-users
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://supercolony.gluster.org/pipermail/gluster-users/attachments/20130102/13a4d66c/attachment.html>