<div dir="ltr"><div class="gmail_extra"><div style>How about this:</div><div style><br></div><div style>"Reference Manual/Guide": This describes how to operate the product. Describe all statements with all options, etc</div>
<div style>"User Manual/Guide": This describes how to "use" the product in various use cases. More of an architectural level.</div><div style>"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.</div>
<div style>"Troubleshoot Manual/Guide": This describes the various troubleshooting scenario's</div><div style>"Developer Manual/Guide": This describes api's, programming examples using various bindings, under the hood info, like xattr meanings, etc.</div>
<div style><br></div><div style>This can also be sections or chapters in a single manual..</div><div style><br></div><div style>Cheers,</div><div style>Fred</div>
<br><br><div class="gmail_quote">On Wed, Jan 2, 2013 at 4:05 PM, Brian Candler <span dir="ltr"><<a href="mailto:B.Candler@pobox.com" target="_blank">B.Candler@pobox.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<div class="im">On Wed, Jan 02, 2013 at 09:03:59AM -0500, Jeff Darcy wrote:<br>
> * A general "principles of operation" guide - not a whole book, but more than<br>
> bits scattered among slide presentations and wiki pages. Let's say something<br>
> that would be on the order of 15-50 pages printed out.<br>
<br>
</div>Personally I'd like to see the details as well as principles. Take<br>
replication as an example: I'd want to know exactly what xattrs are written<br>
and when, what the values mean, what values are seen in intermediate states,<br>
on successful completion and when replication failed. Ditto for<br>
distribution (DHT).<br>
<br>
Since these details may change with the code, I wouldn't mind if they sat in<br>
the git repo alongside the code itself.<br>
<div class="im"><br>
> * Many "cookbook" examples detailing initial configurations for common use<br>
> cases (e.g. media servers, VM storage) and higher-level sequences of steps for<br>
> common operations (e.g. adding servers).<br>
<br>
</div>Not just "common" operations; I believe what's really important is the<br>
uncommon operations in failure scenarios. e.g. replacing a failed server;<br>
replacing a failed brick filesystem within a server; how to diagnose and fix<br>
problems with stuck replication and stuck rebalancing, or when the volume<br>
config is out of sync between peers (which bit me badly).<br>
<br>
I think Red Hat's documentation of LVM is a good example of how this can be<br>
done well:<br>
<br>
<a href="https://access.redhat.com/knowledge/docs/en-US/Red_Hat_Enterprise_Linux/6/html/Logical_Volume_Manager_Administration/" target="_blank">https://access.redhat.com/knowledge/docs/en-US/Red_Hat_Enterprise_Linux/6/html/Logical_Volume_Manager_Administration/</a><br>
<br>
Not only does it give how-to examples of pretty much everything you might<br>
want to do with LVM, it also has a whole section on troubleshooting tools<br>
and recovery procedures, and an appendix on low-level configuration of dm<br>
(analogous to the volfiles in gluster)<br>
<br>
Finally, although I realise that RH is aiming towards a storage appliance, I<br>
still think it would be useful to document how (safely) to manipulate the<br>
volfiles by hand and keep them in sync between peers - the custom<br>
translators are all still there and it would be good to be able to use them,<br>
and this is likely to encourage third-party feature development.<br>
<br>
Regards,<br>
<br>
Brian.<br>
<div class="HOEnZb"><div class="h5">_______________________________________________<br>
Gluster-users mailing list<br>
<a href="mailto:Gluster-users@gluster.org">Gluster-users@gluster.org</a><br>
<a href="http://supercolony.gluster.org/mailman/listinfo/gluster-users" target="_blank">http://supercolony.gluster.org/mailman/listinfo/gluster-users</a><br>
</div></div></blockquote></div><br></div></div>