I am sick and tired of the poor quality of documentation on FreeBSD

Take a look at how it's done on OpenBSD! Take a look at have it's done on Arch Linux!

When there is something that is going to break something during an upgrade, you get timely information and a step by step instruction in what to do - BEFORE you do it!

Something like this doesn't help!
  Pool 'zroot' has the bootfs property set, you might need to update the boot code.
  See gptzfsboot(8) and loader.efi(8) for details.

I might need to update the boot code!? WTF does that even mean?

 I never touched any boot code during installation so I don't even know what that is! And reading those man pages did NOT help me in any way.

So now I got a box that's borked with this beautiful message after updating the zroot pool:

ZFS: unsupported feature: com.delphix:head_errlog
ZFS: pool zroot is not supported
Can't find /boot/zfsloader
Can't find /boot/loader
Can't find /boot/kernel/kernel