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>
