FreeBSD Handbook improvement survey

Reply: Pau Amma : "Follow-up to the FreeBSD Handbook improvement survey"
Go to: [ bottom of page ] [ top of archives ] [ this month ]
From: Pau Amma <pauamma_at_gundo.com>
Date: Sat, 16 Apr 2022 13:04:56 UTC
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)