FreeBSD Handbook improvement survey
17 April, 2022 by pauamma@gundo.com | freebsd
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&2068: 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&1536: document dma - https://bugs.freebsd.org/bugzilla/show_bug.cgi?id&3317: 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&3318: add freebsd-accessibility@ to https://docs.freebsd.org/en/books/handbook/eresources/#eresources-mail - https://bugs.freebsd.org/bugzilla/show_bug.cgi?id&3319: 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&3320; 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&3321: add RAIDz2 and RAIDz3 to the ZFS chapter, including the note in 20.2.2 - https://bugs.freebsd.org/bugzilla/show_bug.cgi?id&1212: update the ZFS chapter for OpenZFS, if needed with 12.x-13.x split - https://bugs.freebsd.org/bugzilla/show_bug.cgi?id&3322: follow-up to https://cgit.freebsd.org/doc/commit/?idr33fc956edc31002c2e8f38ce30dda6b972f24c (explain when and why to upgrade the bootloader) and https://bugs.freebsd.org/bugzilla/show_bug.cgi?id%3364 (documenting the boot partition) unless carlavilla deals with the latter - https://bugs.freebsd.org/bugzilla/show_bug.cgi?id2663: HAST and or CARP: while there, update for 12.x and 13.x - https://bugs.freebsd.org/bugzilla/show_bug.cgi?id"0014: more generally make sure that only things needed early on get in /boot/loader.conf - https://bugs.freebsd.org/bugzilla/show_bug.cgi?id%8264: 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&1025: Change ETSI to etsi2 for Austria Wifi example - https://bugs.freebsd.org/bugzilla/show_bug.cgi?id1952: ipfw NAT no longer requires natd and https://bugs.freebsd.org/bugzilla/show_bug.cgi?id6588: IPFW tables and dummynet if still applicable (see note 1 in costing) - https://bugs.freebsd.org/bugzilla/show_bug.cgi?id"7050: storage device labels, better coverage of GPT: if still applicable - https://bugs.freebsd.org/bugzilla/show_bug.cgi?id"3891: NFSv4 and NFSv4.1 if still applicable - https://bugs.freebsd.org/bugzilla/show_bug.cgi?id!9953: loading graphics drivers needed for suspend/resume at least for some laptops, and https://bugs.freebsd.org/bugzilla/show_bug.cgi?id&0994: 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&1814: typo: s/union to/union in/. - https://bugs.freebsd.org/bugzilla/show_bug.cgi?id&1813: mention smartphones presenting as USB disks, check smartphone when troubleshooting - https://bugs.freebsd.org/bugzilla/show_bug.cgi?id0493: multiconsoles in loader.conf, https://bugs.freebsd.org/bugzilla/show_bug.cgi?id3002: ditto, and https://bugs.freebsd.org/bugzilla/show_bug.cgi?id•408: serial console install if still applicable - https://bugs.freebsd.org/bugzilla/show_bug.cgi?id2370: 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&1944: Soft update and journaling for UFS - https://bugs.freebsd.org/bugzilla/show_bug.cgi?id%7405: pool vs. zpool - https://bugs.freebsd.org/bugzilla/show_bug.cgi?id%4191: 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%7404: track ZFS resources linkrot - https://bugs.freebsd.org/bugzilla/show_bug.cgi?id$0421: use geli attach before zpool import if device is geli-encrypted - https://bugs.freebsd.org/bugzilla/show_bug.cgi?id6521: 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%5323: git vs. gitup and Game of Trees (got) - https://bugs.freebsd.org/bugzilla/show_bug.cgi?id&0007: 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%7818 and https://reviews.freebsd.org/D31612 - https://bugs.freebsd.org/bugzilla/show_bug.cgi?id%7618: 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%3874 (dd arguments) and s/Write the Image/write the image/ while there. - https://bugs.freebsd.org/bugzilla/show_bug.cgi?id"3997 (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%3392 (boot_mute="NO" and other 13.x changes) needs discussion of where it would go - https://bugs.freebsd.org/bugzilla/show_bug.cgi?id%2951 (chsh asks for user's password) - https://bugs.freebsd.org/bugzilla/show_bug.cgi?id%2893 (smb.conf) unless "map to guest" should still be specified - https://bugs.freebsd.org/bugzilla/show_bug.cgi?id%2423 memoryuse (add vmemoryuse) - https://bugs.freebsd.org/bugzilla/show_bug.cgi?id%2069 plasma5-plasma and gnome-shell in addition to the complete versions - https://bugs.freebsd.org/bugzilla/show_bug.cgi?id%0927 (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$6091 "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$7568 (the Handbook part of ipf(7)) - https://bugs.freebsd.org/bugzilla/show_bug.cgi?id&3232 (clarify uses of GELI and UFS in installer chapter, add (Open)ZFS ~ encryption caveat) - https://bugs.freebsd.org/bugzilla/show_bug.cgi?id&3323: 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&3324: 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&3326: 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&3327: In Linux Binary compatibility, Advanced Topics, link to debootstrap in the 10.5.1 note - https://bugs.freebsd.org/bugzilla/show_bug.cgi?id&3328: Merge wiki Linux jails content into Linux Binary compatibility, debootstrap - https://bugs.freebsd.org/bugzilla/show_bug.cgi?id&2689: 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$5512: Kazakhstan mirrors (If these mirrors are still current, which protocols do they use?) - https://bugs.freebsd.org/bugzilla/show_bug.cgi?id&3329: Link to Development model book in FreeBSD Handbook Introduction, history - https://bugs.freebsd.org/bugzilla/show_bug.cgi?id$8150: document using jail.conf instead of rc.conf, mention etcupdate - https://bugs.freebsd.org/bugzilla/show_bug.cgi?id&3330: Extend the FreeBSD Handbook jails section to mention iocage - https://bugs.freebsd.org/bugzilla/show_bug.cgi?id&3331Explain use of bectl (if using ZFS) in the updating FreeBSD section of the FreeBSD Handbook - https://bugs.freebsd.org/bugzilla/show_bug.cgi?id&3332: Remove spurious "because" in ZFS Features and Terminology caution - https://bugs.freebsd.org/bugzilla/show_bug.cgi?id&3333: Check for lingering 11.x (and earlier) and 12.2 references in the FreeBSD handbook - https://bugs.freebsd.org/bugzilla/show_bug.cgi?id&3334: Remove NIS section from FreeBSD Handbook if no longer in use. - https://bugs.freebsd.org/bugzilla/show_bug.cgi?id&3335: Add GPT discussion to FreeBSD Basics, Disk Organization in FreeBSD Handbook - https://bugs.freebsd.org/bugzilla/show_bug.cgi?id&3336: Make sure all FreeBSD Handbook images including non-text screenshots have descriptions or text alternatives - https://bugs.freebsd.org/bugzilla/show_bug.cgi?id&3337: Make sure all FreeBSD Handbook procedures have mouseless or keyboard-only equivalents - https://bugs.freebsd.org/bugzilla/show_bug.cgi?id&3338: Style conformance pass over the whole FreeBSD Handbook, including removing uses of the second person - https://bugs.freebsd.org/bugzilla/show_bug.cgi?id&3339: Proofread the whole FreeBSD Handbook - https://bugs.freebsd.org/bugzilla/show_bug.cgi?id&3340: 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%5318 (if 0mp is, otherwise see https://cgit.freebsd.org/doc/commit/?idr33fc956edc31002c2e8f38ce30dda6b972f24c above) - https://bugs.freebsd.org/bugzilla/show_bug.cgi?id&2742 - https://bugs.freebsd.org/bugzilla/show_bug.cgi?id%9494 - https://bugs.freebsd.org/bugzilla/show_bug.cgi?id&2274 - https://bugs.freebsd.org/bugzilla/show_bug.cgi?id 4918 - https://bugs.freebsd.org/bugzilla/show_bug.cgi?id&0812 (Graham Perrin may have something in the works) - https://bugs.freebsd.org/bugzilla/show_bug.cgi?id$2984 is carlavilla still working on this one? - https://bugs.freebsd.org/bugzilla/show_bug.cgi?id%4153 is carlavilla still working on this one? - https://bugs.freebsd.org/bugzilla/show_bug.cgi?id&0183 carlavilla may have something in the works - https://bugs.freebsd.org/bugzilla/show_bug.cgi?id%7818 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&0007 - https://bugs.freebsd.org/bugzilla/show_bug.cgi?id%3453 and https://reviews.freebsd.org/D28622 (phk/debdrup) - need to review - https://bugs.freebsd.org/bugzilla/show_bug.cgi?id 0803 (is it a manual page change, a doc change, or both?) - https://bugs.freebsd.org/bugzilla/show_bug.cgi?id$1673 (gbe?) - https://bugs.freebsd.org/bugzilla/show_bug.cgi?id$4156 (blackend?) - https://bugs.freebsd.org/bugzilla/show_bug.cgi?id$7285 still applicable with the current doc-building toolchain (doceng, as discussed in IRC) - https://bugs.freebsd.org/bugzilla/show_bug.cgi?id%3364 (documenting the boot partition) (carlavilla) - https://bugs.freebsd.org/bugzilla/show_bug.cgi?id6588 (is tmj@ still working on this?) Unsure of current completion status: - https://bugs.freebsd.org/bugzilla/show_bug.cgi?id%2893 - https://bugs.freebsd.org/bugzilla/show_bug.cgi?id$1683 is this (that is, the workaround using MIT Kerberos) still needed? - https://bugs.freebsd.org/bugzilla/show_bug.cgi?id6343 ipsec gif setup: partly fixed, maybe completely - was https://bugs.freebsd.org/bugzilla/show_bug.cgi?id&0253 applied silently or is https://bugs.freebsd.org/bugzilla/show_bug.cgi?id%6725 a duplicate or related? - https://bugs.freebsd.org/bugzilla/show_bug.cgi?id%7481 (no images in epub) if still applicable - Review https://bugs.freebsd.org/bugzilla/show_bug.cgi?id%7404 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)