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

On Tuesday, November 21st, 2023 at 6:10 PM, iio7@tutanota.com <iio7@tutanota.com> wrote:


> 
> 
> > Nov 21, 2023, 21:30 by steve@sohara.org:
> > 
> > > You did of course read the release notes right ? The rather good
> > > documentation provided by the FreeBSD project for each new release.
> > > Specifically this section that tells you exactly what to do and why.
> > > 
> > > https://www.freebsd.org/releases/14.0R/relnotes/#upgrade
> > > 
> > > Documentation is only useful if you read it! BEFORE you do things.
> > > 
> > > > 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.
> > > 
> > > It's a warning not documentation, heeding it could have saved you
> > > much trouble.
> > > 
> > > > I might need to update the boot code!? WTF does that even mean?
> > > 
> > > It seems pretty clear that you should make sure you understand it
> > > and do what is necessary before you reboot. The boot code is (as the name
> > > implies) the code used to boot the system which has to be able to read the
> > > filesystem containing the OS, which it can't if that filesystem has been
> > > updated with features that the existing boot code does not support.
> > > 
> > > > 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.
> > > 
> > > If you had read the release notes you would know what to do, and
> > > surely the name "boot code" is sufficiently descriptive as to what it is.
> > > 
> > > > So now I got a box that's borked with this beautiful message after
> > > > updating the zroot pool:
> > > 
> > > AND rebooting without updating the boot code right ?
> > > 
> > > > 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
> > > 
> > > Now you're going to need this article in the forums which a search
> > > would have found for you in a few seconds:
> > > 
> > > https://forums.freebsd.org/threads/upgrade-14-relase-root-on-zfs-reboot-before-update-boot-code-and-stuck-at-efi-shell.91035/
> > > 
> > > You might want to thank T-Aoki and note the rather more polite way
> > > someone else who got themselves into this mess asked for help.
> 
> 
> The release engineering and related documentation suck as usual. Polite my ass. I have had it.
> 
> I have been on FreeBSD for more than 20 years and always have to deal with shitload of problems on this operating system ONLY due to the lack of documentation.
> 
> I read the man pages, I read the forum post, which doesn't help shit when the next crap you run into is this:
> 
> ZFS: unsupported feature: com.klarasystems:vdev_zaps_vs
> 
> Nothing should break this bad during a simple upgrade and then have the guy responsible for the documentation to make a fucking blog post about the missing documentation on the website:
> 
> https://www.daemonology.net/blog/2023-11-21-late-breaking-FreeBSD-14-breakage.html
> 
> "but there are a few last-minute issues which deserve to bedocumented — probably somewhere on the FreeBSD website, but I canpost to my blog much faster and hopefully we'll get these onto the FreeBSDwebsite later."
> 
> Oh, and let's not forget this one:
> 
> "stand: Fix oversight in updating OpenZFS: Add com.klarasystems:vdev_zaps_v2com.klarasystems:vdev_zaps_v2 is a new feature that the last OpenZFSimport brought in. It needs to be on the list of supported features, butthat update didn't happen so I woke up to a mailbox with multiplecomplaints."
> 
> Thank you very much! Amazing work.

I can understand your frustration. But at the same time, if you're angry, 
wait until that passes, and then send an email. FreeBSD does not charge 
you anything to use their operating system, a lot of people contribute 
in their free time, and mistakes can happen. 

As far as documentation goes, the various FreeBSD handbooks are superb (to me),
while the Arch Wiki doesn't really do it for me. It can be different strokes for
different folks.