Re: [Bug 287148] Handbook chapter 22 on ZFS is so outdated it is actually plainly wrong today

On Thu, May 29, 2025, at 10:31, bugzilla-noreply@freebsd.org wrote:
> Now I was certain that at least FreeBSD's own docs would of course show how to
> create a proper GPT partition to use for ZFS etc. and wanted to drop them a
> link to the handbook.
> 
> To my great surprise and dismay the handbook uses procedures like this:
> 
> zpool create example /dev/da0

I assume you're referring to a bootable device? Using a whole device is currently recommended: 
https://openzfs.github.io/openzfs-docs/man/master/7/zpoolconcepts.7.html

"ZFS can use individual slices or partitions, though the recommended mode of operation is to use whole disks."

> And in the next code example it references devices like /dev/ad0s1a.

Agree. This appears to be inconsistent/wrong.

> This entire chapter is misleading, downright dangerous, and in conflict with
> the structures our installer actually produces.

I'm not sure I think the chapter is bad overall, but I do agree it makes sense to call out what the installer will do and considerations for that versus if you were setting up, for example, a non-bootable two-device mirror for storage. Maybe a "Partitions Consideration" section could be useful. 

The existing doc does call attention to this a bit in 22.3.1 under zpool administration, but makes no mention under quick start.

I definitely see how it could cause confusion as-is. Seems like a good improvement suggestion overall.