Project GRUDS: Handbook disk reorg

[Warren Block]

On Mon, 15 Jul 2013, Allan Jude wrote:

> Notes:
> Quick-start section should probably cover installation with 'root on zfs'

Excellent point!  We really need to make the quick start sections almost 
mandatory.  Added to outline.

> Hardware chapter might mention SAS and things like SAS expanders and
> other enterprise hardware considerations

Yes.  Added to outline.

> The metadata storage location conflicts chapter is a really good idea.
> whole-disk GEOM + GPT is basically not possible, so you get in to
> per-partition GEOMs

There is a little section about this in the new RAID1 (gmirror) section.

> The labels bit should probably talk a bit about ZFS gUIDs and how ZFS
> does labels (this is both metadata and a label...) too

Added to outline.

> The GEOM chapter should have at least a small stub for each GEOM type,
> like cache, journal, multipath, etc

Agreed.  The hard part is getting people to write the missing ones.

> For the ZFS chapter, this is the structure that bcr@ and myself proposed
> at the last docsprint (this is probably a lot more detail than you need,
> but if anyone has suggestions or ideas for additional things to do,
> please let me know):
>
> ZFS
>    - ZFS introduction (what is ZFS)
>    - ZFS Features and Terminology (giant table of definitions)

I have not really looked at the new section yet, but I did see the giant 
table.  Personally, I'd rather have a gentle introduction that builds 
up, and then definitions later.  It reminds me of instructions on 
recording menus for phone systems.  They said not to put the number 
first ("Press one for..."), because it gives people anxiety about 
remembering that number.  Instead, put the description first, then the 
thing to remember last: "For help, press one."  In computer terms, a lot 
of definitions I have to remember won't help me as much as an 
introductory section that says "ZFS storage devices, called *zpools*, 
can be a single disk or group of disks."  And then build on that. 
Later sections would have full detail and definitions.

Thanks!