There is one more problem with the new documentation.
The Documentation has an article for pools, datasets and zvols.
But there is no article that gives an overview and direction or best practice tips when to use a dataset and when to use a zvol.
It also doesn't give some suggestions how datasets should be arranged and when someone should nest datasets and zvols in a top level dataset.
For what i have found out so far is the following:
1. It makes sense to create one top level dataset. This makes the task to create Snapshots, Replication and Backups easier.
2. Datasets are for file bases storages, like SMB and nfs shares. Zvols are virtual block devices and are required for Virtual Machines or iSCSI devices. It's possible to nest zvols within datasets.
3. zvol need a size that must be given before creating them. The size can be increased later, but not decreased. If you need 100 GB for a VM, you create a 100 GB zvol and these 100 GB get reserved and can't be used for something else outside of that zvol scope. Thus the free space of your pool decreases. That's not the case for datasets, their reserved space can increase when they grow and decreased when files are deleted.
4. For performance reasons zvols should be put on a pool of mirrors, not on raidz[n]. The size of a zvol shouldn't surpass 80 % of the available space of a pool. If the task of a VM is input/output intensive, like a database running on the VM, the pool for the zvol should be based on SSDs. It's possible to mix datasets and zvols. Jails don't need zvol, they work fine with datasets.
These infos should be in the documentation.
If i get something wrong, please correct me.
If you have more information, then add it.