From owner-freebsd-doc@FreeBSD.ORG Tue Jul 16 03:08:06 2013 Return-Path: Delivered-To: freebsd-doc@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) by hub.freebsd.org (Postfix) with ESMTP id A60C5F2F for ; Tue, 16 Jul 2013 03:08:06 +0000 (UTC) (envelope-from wblock@wonkity.com) Received: from wonkity.com (wonkity.com [67.158.26.137]) by mx1.freebsd.org (Postfix) with ESMTP id 4DECEAF0 for ; Tue, 16 Jul 2013 03:08:06 +0000 (UTC) Received: from wonkity.com (localhost [127.0.0.1]) by wonkity.com (8.14.7/8.14.7) with ESMTP id r6G384Mm075322; Mon, 15 Jul 2013 21:08:04 -0600 (MDT) (envelope-from wblock@wonkity.com) Received: from localhost (wblock@localhost) by wonkity.com (8.14.7/8.14.7/Submit) with ESMTP id r6G38337075319; Mon, 15 Jul 2013 21:08:04 -0600 (MDT) (envelope-from wblock@wonkity.com) Date: Mon, 15 Jul 2013 21:08:03 -0600 (MDT) From: Warren Block To: Allan Jude Subject: Re: Project GRUDS: Handbook disk reorg In-Reply-To: <51E4915F.9010303@allanjude.com> Message-ID: References: <51E4915F.9010303@allanjude.com> User-Agent: Alpine 2.00 (BSF 1167 2008-08-23) MIME-Version: 1.0 Content-Type: TEXT/PLAIN; format=flowed; charset=US-ASCII X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.4.3 (wonkity.com [127.0.0.1]); Mon, 15 Jul 2013 21:08:04 -0600 (MDT) Cc: freebsd-doc@freebsd.org X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 16 Jul 2013 03:08:06 -0000 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!