FreeBSD Handbook improvement survey

Skip to first unread message

Pau Amma

Apr 17, 2022, 12:00:05 AMApr 17
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
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
- change the
example to a sound driver more likely not to be in generic than snd_hda
or remove it altogether)
- document dma
- reorder
etcupdate steps in Handbook section 24.5
( by
moving the warning in to the place in the procedure where users
would need to perform it when applicable
- add
freebsd-accessibility@ to
- add an
accessibility section to the Handbook, per
-; fix errant
references to /etc/X11/xorg.conf in and (that goes beyond the
Handbook, but I think it makes sense to tackle them together)
- add RAIDz2
and RAIDz3 to the ZFS chapter, including the note in 20.2.2
- update the
ZFS chapter for OpenZFS, if needed with 12.x-13.x split
- follow-up to
(explain when and why to upgrade the bootloader) and (documenting
the boot partition) unless carlavilla deals with the latter
- HAST and or
CARP: while there, update for 12.x and 13.x
- more
generally make sure that only things needed early on get in
- 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
- Change ETSI
to etsi2 for Austria Wifi example
- ipfw NAT no
longer requires natd and IPFW tables
and dummynet if still applicable (see note 1 in costing)
- storage
device labels, better coverage of GPT: if still applicable
- NFSv4 and
NFSv4.1 if still applicable
- loading
graphics drivers needed for suspend/resume at least for some laptops,
and 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.
- typo:
s/union to/union in/.
- mention
smartphones presenting as USB disks, check smartphone when
multiconsoles in loader.conf, ditto, and serial console
install if still applicable
- 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
- Soft update
and journaling for UFS
- pool vs.
- exFAT and
FAT32 using for
exFAT (
doesn't show anything promising for FAT32)
- track ZFS
resources linkrot
- use geli
attach before zpool import if device is geli-encrypted
- 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.
- git vs.
gitup and Game of Trees (got)
- 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 and
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
merge "virtualization (Virtualization)" into a link and remove the
anchor from the URL unless needed in the single-HTML version
- (dd
arguments) and s/Write the Image/write the image/ while there.
- (portrange
sysctl tuning in
who knows about that? Did any later commits change the default/initial
(boot_mute="NO" and other 13.x changes) needs discussion of where it
would go
- (chsh asks
for user's password)
- (smb.conf)
unless "map to guest" should still be specified
- memoryuse
(add vmemoryuse)
plasma5-plasma and gnome-shell in addition to the complete versions
- (may need to
experiment with no_radr and accept_rtadv, in which case see note 1 on
- "pkg
bootstrap" no longer needed, and it's all supported versions now, not 10
and later
- (the Handbook
part of ipf(7))
- (clarify uses
of GELI and UFS in installer chapter, add (Open)ZFS ~ encryption caveat)
- update
if/as needed for ZFS and (U)EFI
- 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
- Add QEMU
discussion in the FreeBSD Handbook virtualization chapter unless the
audience is too small/specialized.
- In Linux
Binary compatibility, Advanced Topics, link to debootstrap in the 10.5.1
- Merge wiki
Linux jails content into Linux Binary compatibility, debootstrap
- track
removal of i386-wine in; while there, s/might
want it do so/might want to do so/ in
- Kazakhstan
mirrors (If these mirrors are still current, which protocols do they
- Link to
Development model book in FreeBSD Handbook Introduction, history
- document
using jail.conf instead of rc.conf, mention etcupdate
- Extend the
FreeBSD Handbook jails section to mention iocage
- use of
bectl (if using ZFS) in the updating FreeBSD section of the FreeBSD
- Remove
spurious "because" in ZFS Features and Terminology caution
- Check for
lingering 11.x (and earlier) and 12.2 references in the FreeBSD handbook
- Remove NIS
section from FreeBSD Handbook if no longer in use.
- Add GPT
discussion to FreeBSD Basics, Disk Organization in FreeBSD Handbook
- Make sure
all FreeBSD Handbook images including non-text screenshots have
descriptions or text alternatives
- Make sure
all FreeBSD Handbook procedures have mouseless or keyboard-only
- Style
conformance pass over the whole FreeBSD Handbook, including removing
uses of the second person
- Proofread
the whole FreeBSD Handbook
- Make sure
all procedures still work and update output text as needed

Things others started/are working on:
- (if 0mp is,
otherwise see
- (Graham
Perrin may have something in the works)
- is carlavilla
still working on this one?
- is carlavilla
still working on this one?
- carlavilla
may have something in the works
- and (gbe), which touches on some of the
same issues as
- and (phk/debdrup) - need to review
- (is it a
manual page change, a doc change, or both?)
- (gbe?)
- (blackend?)
- still
applicable with the current doc-building toolchain (doceng, as discussed
in IRC)
- (documenting
the boot partition) (carlavilla)
- (is tmj@
still working on this?)

Unsure of current completion status:
- is this (that
is, the workaround using MIT Kerberos) still needed?
- ipsec gif
setup: partly fixed, maybe completely
- was applied
silently or is
a duplicate or related?
- (no images in
epub) if still applicable
- Review or
otherwise move it forward

#BlackLivesMatter #TransWomenAreWomen #AccessibilityMatters
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)

Reply all
Reply to author
0 new messages