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

On 11/21/23 14:12, Paul Procacci wrote:
> 
> 
> On Tue, Nov 21, 2023 at 2:51 PM <iio7@tutanota.com 
> <mailto:iio7@tutanota.com>> wrote:
> 
>     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
> 
> 
> 
> 
> You failed to, in your own words, "get timely information and a step by 
> step instruction in what to do - BEFORE you _did_ it!"
> 
> You're now suffering with the errors that you cause upon yourself.
> 

I'm not a fan of the overall attitude towards them (their concern isn't 
completely unfounded, not that I like their tone either), but I agree 
with the overall sentiment.  The e-mail that started this thread is a 
lot less helpful than the e-mail that could have been sent instead if 
they had stopped when they realized they didn't understand from the 
information given- to figure out what the ramifications of proceeding 
are (surely this upgrade wasn't that urgent) and point out that 
documentation actually isn't as helpful as one might think to a user of 
a different background.

> Quite literally 1000's upon 1000's upgrade their machines daily I'd 
> gather.  You are the odd man out.  See the problem here?
> 
> ~Paul
> 

Thanks,

Kyle Evans