FreeBSD Handbook improvement survey

[Pau Amma]

The FreeBSD Foundation contracted me to develop a prioritized plan for
improving and updating the FreeBSD Handbook. For the first stage of this
project, I have identified a number of issues needing improvement. To
prioritize the issues, please tell me which are important to you
personally. Specifically, please rate each of the items listed:
critical, important, useful, neutral (or no opinion), counterproductive.
If you chose "counterproductive", please explain why. If there are
things you'd like changed that I haven't listed, please add them and
rate them as above. Please respect the Reply-to and don't reply to all.
At this stage I am focusing on the English version, so please answer
based on that version's content, but translations may be updated to the
extent that translation teams are available.

I intend to close this survey on April 30 at 11:59:59pm UTC (see
https://www.timeanddate.com/worldclock/fixedtime.html?msg=End+of+survey+answer+collection&iso=20220430T235959&p1=%3A
for the equivalent in your timezone). To allow for delays email
delivery, please try replying at least 90 minutes before the deadline.

Main list of items with some annotations for context, in no particular
order:
- https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=262068: change the
example to a sound driver more likely not to be in generic than snd_hda
or remove it altogether)
- https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=261536: document dma
- https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=263317: reorder
etcupdate steps in Handbook section 24.5
(https://docs.freebsd.org/en/books/handbook/cutting-edge/#makeworld) by
moving the warning in 24.5.6.1 to the place in the procedure where users
would need to perform it when applicable
- https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=263318: add
freebsd-accessibility@ to
https://docs.freebsd.org/en/books/handbook/eresources/#eresources-mail
- https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=263319: add an
accessibility section to the Handbook, per
https://lists.freebsd.org/archives/freebsd-doc/2021-September/000479.html
- https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=263320; fix errant
references to /etc/X11/xorg.conf in
https://docs.freebsd.org/en/books/handbook/x11/ and
https://docs.freebsd.org/en/books/faq/#X11 (that goes beyond the
Handbook, but I think it makes sense to tackle them together)
- https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=263321: add RAIDz2
and RAIDz3 to the ZFS chapter, including the note in 20.2.2
- https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=261212: update the
ZFS chapter for OpenZFS, if needed with 12.x-13.x split
- https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=263322: follow-up to
https://cgit.freebsd.org/doc/commit/?id=7233fc956edc31002c2e8f38ce30dda6b972f24c
(explain when and why to upgrade the bootloader) and
https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=253364 (documenting
the boot partition) unless carlavilla deals with the latter
- https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=192663: HAST and or
CARP: while there, update for 12.x and 13.x
- https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=220014: more
generally make sure that only things needed early on get in
/boot/loader.conf
- https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=258264: unclear
whether it can be loaded in rc.conf, needs an update to recent driver;
I'd need help from someone who has a computer using an NVIDIA GPU to
work on that one
- https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=261025: Change ETSI
to etsi2 for Austria Wifi example
- https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=121952: ipfw NAT no
longer requires natd and
https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=116588: IPFW tables
and dummynet if still applicable (see note 1 in costing)
- https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=227050: storage
device labels, better coverage of GPT: if still applicable
- https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=223891: NFSv4 and
NFSv4.1 if still applicable
- https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=219953: loading
graphics drivers needed for suspend/resume at least for some laptops,
and https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=260994: KMS needs
DRM drivers for suspend and resume even on console-only hosts. I'm not
sure I can help with this, though. It depends on whether console-mode
VMs can suspend under VirtualBox.
- https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=261814: typo:
s/union to/union in/.
- https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=261813: mention
smartphones presenting as USB disks, check smartphone when
troubleshooting
- https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=180493:
multiconsoles in loader.conf,
https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=183002: ditto, and
https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=95408: serial console
install if still applicable
- https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=172370: Blu-Ray) if
my HL-DT-ST DVDRAM GUA0N AL00 work as a Blu-Ray drive (DuckDuckGo hints
it may) or someone who has one can help
- https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=261944: Soft update
and journaling for UFS
- https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=257405: pool vs.
zpool
- https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=254191: exFAT and
FAT32 using
https://github.com/relan/exfat/blob/v1.3.0/fuse/mount.exfat-fuse.8 for
exFAT (https://github.com/search?p=2&q=fat32+fuse&type=Repositories
doesn't show anything promising for FAT32)
- https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=257404: track ZFS
resources linkrot
- https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=240421: use geli
attach before zpool import if device is geli-encrypted
- https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=146521: ping6
instructions for testing IPv6, since it and ping are different in 12.x.
Since 13.x merged ping is supposed to be backward-compatible when
invoked as ping6, no need for separate discussion.
- https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=255323: git vs.
gitup and Game of Trees (got)
- https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=260007: Refactor
version list in FreeBSD Handbook intro (and other books as needed) for
easier update; needs discussion of where it should go and which other
books or articles should use it; see also
https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=257818 and
https://reviews.freebsd.org/D31612
- https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=257618:
vm.bios.efi=1 in Advanced Settings to allow booting in a Parallels VM;
I'll need help from someone with a Macbook (or other Macintosh) for that
- In FreeBSD Handbook pre-installation tasks step 2
(https://docs.freebsd.org/en/books/handbook/bsdinstall/#bsdinstall-pre),
merge "virtualization (Virtualization)" into a link and remove the
anchor from the URL unless needed in the single-HTML version
- https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=253874 (dd
arguments) and s/Write the Image/write the image/ while there.
- https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=223997 (portrange
sysctl tuning in
https://docs.freebsd.org/en/books/handbook/config/#configtuning-kernel-limits):
who knows about that? Did any later commits change the default/initial
values?
- https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=253392
(boot_mute="NO" and other 13.x changes) needs discussion of where it
would go
- https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=252951 (chsh asks
for user's password)
- https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=252893 (smb.conf)
unless "map to guest" should still be specified
- https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=252423 memoryuse
(add vmemoryuse)
- https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=252069
plasma5-plasma and gnome-shell in addition to the complete versions
- https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=250927 (may need to
experiment with no_radr and accept_rtadv, in which case see note 1 on
costing)
- https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=246091 "pkg
bootstrap" no longer needed, and it's all supported versions now, not 10
and later
- https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=247568 (the Handbook
part of ipf(7))
- https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=263232 (clarify uses
of GELI and UFS in installer chapter, add (Open)ZFS ~ encryption caveat)
- https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=263323: update
https://docs.freebsd.org/en/books/handbook/boot/index.html#boot-synopsis
if/as needed for ZFS and (U)EFI
- https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=263324: Move/copy
reference to virtualization in the installation chapter somewhere more
obvious than preinstall step 2, like in the synopsis, with a reference
to install images being usable for that as well
- https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=263326: Add QEMU
discussion in the FreeBSD Handbook virtualization chapter unless the
audience is too small/specialized.
- https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=263327: In Linux
Binary compatibility, Advanced Topics, link to debootstrap in the 10.5.1
note
- https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=263328: Merge wiki
Linux jails content into Linux Binary compatibility, debootstrap
- https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=262689: track
removal of i386-wine in
https://docs.freebsd.org/en/books/handbook/wine/; while there, s/might
want it do so/might want to do so/ in
https://docs.freebsd.org/en/books/handbook/wine/#installing-wine-on-freebsd
- https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=245512: Kazakhstan
mirrors (If these mirrors are still current, which protocols do they
use?)
- https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=263329: Link to
Development model book in FreeBSD Handbook Introduction, history
- https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=248150: document
using jail.conf instead of rc.conf, mention etcupdate
- https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=263330: Extend the
FreeBSD Handbook jails section to mention iocage
- https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=263331Explain use of
bectl (if using ZFS) in the updating FreeBSD section of the FreeBSD
Handbook
- https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=263332: Remove
spurious "because" in ZFS Features and Terminology caution
- https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=263333: Check for
lingering 11.x (and earlier) and 12.2 references in the FreeBSD handbook
- https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=263334: Remove NIS
section from FreeBSD Handbook if no longer in use.
- https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=263335: Add GPT
discussion to FreeBSD Basics, Disk Organization in FreeBSD Handbook
- https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=263336: Make sure
all FreeBSD Handbook images including non-text screenshots have
descriptions or text alternatives
- https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=263337: Make sure
all FreeBSD Handbook procedures have mouseless or keyboard-only
equivalents
- https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=263338: Style
conformance pass over the whole FreeBSD Handbook, including removing
uses of the second person
- https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=263339: Proofread
the whole FreeBSD Handbook
- https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=263340: Make sure
all procedures still work and update output text as needed

Things others started/are working on:
- https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=255318 (if 0mp is,
otherwise see
https://cgit.freebsd.org/doc/commit/?id=7233fc956edc31002c2e8f38ce30dda6b972f24c
above)
- https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=262742
- https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=259494
- https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=262274
- https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=204918
- https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=260812 (Graham
Perrin may have something in the works)
- https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=242984 is carlavilla
still working on this one?
- https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=254153 is carlavilla
still working on this one?
- https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=260183 carlavilla
may have something in the works
- https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=257818 and
https://reviews.freebsd.org/D31612 (gbe), which touches on some of the
same issues as https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=260007
- https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=253453 and
https://reviews.freebsd.org/D28622 (phk/debdrup) - need to review
- https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=200803 (is it a
manual page change, a doc change, or both?)
- https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=241673 (gbe?)
- https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=244156 (blackend?)
- https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=247285 still
applicable with the current doc-building toolchain (doceng, as discussed
in IRC)
- https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=253364 (documenting
the boot partition) (carlavilla)
- https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=116588 (is tmj@
still working on this?)

Unsure of current completion status:
- https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=252893
- https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=241683 is this (that
is, the workaround using MIT Kerberos) still needed?
- https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=196343 ipsec gif
setup: partly fixed, maybe completely
- was https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=260253 applied
silently or is https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=256725
a duplicate or related?
- https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=257481 (no images in
epub) if still applicable
- Review https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=257404 or
otherwise move it forward

--
#BlackLivesMatter #TransWomenAreWomen #AccessibilityMatters
#StandWithUkrainians
English: he/him/his (singular they/them/their/theirs OK)
French: il/le/lui (iel/iel and ielle/ielle OK)
Tagalog: siya/niya/kaniya (please avoid sila/nila/kanila)