Solved FreeBSD Handbook improvement surveys – announcement and background

grahamperrin

grahamperrin

 
For the benefit of people who do not have a full subscription to freebsd-announce:
Pau Amma invites responses to his e-mail:

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 …
Click to expand...

Attached​


Printed from the e-mail:
(Archived copies of the e-mail suffer from narrow wrapping, which decreases legibility. The original e-mail did not have this problem.)

Related​


Q1 2022 Software Development Projects Update | FreeBSD Foundation
Handbook Revitalization

The FreeBSD Handbook needs revitalization. Many FreeBSD components are either not documented or the documentation is outdated. As such, the Foundation has contracted Pau Amma to begin this work. The first goal for the project is to determine what work needs to be done to make the Handbook a better resource, so that both new and seasoned FreeBSD users can easily find quality instruction to set up and configure a FreeBSD system. Pau also plans to make the Handbook more accessible for those using screen readers or mouseless systems.
Click to expand...

FreeBSD bug 263315 – Tracking bug for the FreeBSD handbook revamping contract
Please don't change this bug or attach/detach others without my (pauamma@⋯) permission.

Sponsored by: the FreeBSD Foundation
Click to expand...
 

Attachments

  • FreeBSD Handbook improvement survey 2022-04-16 - A4.pdf
    189.5 KB · Views: 241
  • FreeBSD Handbook improvement survey 2022-04-16 - A3.pdf
    168.5 KB · Views: 165
Nyantastic said:
… how to respond …
Click to expand...

Food for thought

Without looking at any bug report (or the collection): which one chapter, or section within a chapter, would you most like to see improved?

For the collection: do the titles help you to think how to respond?

(If the e-mail had included titles, in addition to annotations, it might have been two or three times as long.)​

FreeBSD Handbook Gets a New Layout (2021) – small parts of this five-page topic concerned content (more than layout).

– responses to Pau, please, as outlined in his e-mail.​


In freebsd-questions:
 
Does the three panel layout have some purpose beyond the redisplay of expanded chapters headings as a redundant 'table of contents' on the right? Does gray on white text rather than black on white text reduce or induce eye strain? It may be that I'm becoming an old curdmudgeon and simply hate new things but I liked the old layout. While the new is certainly not terrible as some, new reddit comes to mind, it doesn't improve readability for me. I'll be happy to read correct and good information either way but navigating change for its own sake becomes increasingly tedious with my increasing years. For example, I've yet to see a link to this survey, on the email or on this page. Surely this is the result of some ignorance on my part but even attempts to follow links to bugs listed in the email result in impasse at bugzilla which tells me things like ''262068:' is not a valid bug number nor an alias to a bug" and so it goes and it is increasingly tiresome.
 
roper said:
Does the three panel layout have some purpose
Click to expand...
No.

roper said:
Does gray on white text rather than black on white text reduce or induce eye strain?
Click to expand...
It decreases readability.

The new layout was not designed by one who is versed in such things. It irritates me that, three times, I discussed working with the Foundation on a new layout--cause that was what my company did--but was met with apathy. I don't know how Pau got invited to do the work when I offered professional work for free. I admit that the lack of encouragement did not make me pursue it as vigorously as I should have but what do you expect for free.
 
The old layout was much better.

Also in the chapter on jails I think it would benefit many to have a section on VNET, talk about how it compares to traditional (ip aliased) jails, and the advantages. Of course this information can be found by browsing around and Michael Lucas discusses the basics in his book. Still it would be nice to have an official source to reference.
 
I personally would like to be included or mentioned mpd5 as an alternative over pppoe in chapter: "28.4. Using PPP over Ethernet (PPPoE)"
 
zsolt said:
I personally would like to be included or mentioned mpd5 as an alternative over pppoe in chapter: "28.4. Using PPP over Ethernet (PPPoE)"
Click to expand...
Handbook should contain only the base system setup / diagnostics / troubleshoot. All other installation guides should be placed in Wiki pages.
Regarding the "new" theme of the handbook i doesn't like the usage of google's inter regular 400 16px font which looks ugly without ClearType. As easy fix it can be included in separate theme to choose or remove it completely and leave the browser to select the default OS fonts.

example: No ClearType inter font

1650451940469.png

fonts.google.com

Inter - Google Fonts

Inter is a variable font family carefully crafted & designed for computer screens. Inter features a tall x-height to aid in readability of mixed-case and lower-
fonts.google.com fonts.google.com
 
VladiBG said:
Handbook should contain only the base system setup / diagnostics / troubleshoot. All other installation guides should be placed in Wiki pages.
Click to expand...
Agreed. Handbook tends to get outdated, and the more work is invested in it, the more reluctant one becomes about re-working it.
I use handbook only when I hit a topic where I am unfamiliar with and need a rough&quick approach for a beginning, As this then has to be refactored anyway, it it not so critical.

There are many topics which carry stuff so you could write a separate book about them, say, IPv6 done properly, or dummynet, or netgraph - and there one usually ends up with no proper documentation whatsoever and has to go for trial&error, experimenting or reading the source.
Examples and use-cases then appear on github, where one will never find them.
 
roper said:
… following links with a web browser.
Click to expand...

OK, now I see the problem. Thanks. The problem affects the three archives, but not the original e-mail (viewed in Thunderbird).

You can avoid the problem by using either of the PDFs.
 
roper said:
Sylpheed …
Click to expand...

Not as neat as Thunderbird, however the links are free from breakage:

1650575800178.png

A few days ago there was the possibility of sharing an .eml file, which (pictured above) can be used with clients such as Thunderbird and Sylpheed.
 
Changes/decisions/new requirements should be on all handbooks as soon it was decided what is the new defaults, and this implies the Porter's Handbook too.
 
roper said:
Does the three panel layout have some purpose beyond the redisplay of expanded chapters headings as a redundant 'table of contents' on the right?
Click to expand...
More garbage, less content :(

roper said:
Does gray on white text rather than black on white text reduce or induce eye strain?
Click to expand...
Low-contrast is "modern" but makes reading hard for me, and this in turn lowers my mood and makes me aggressive as I have a hard time straining my eyes trying to read.
In particular, it is very annoying when one considers that the actual reason for this is preferring to mindlessly follow the newest "cool" fad trends

roper said:
It may be that I'm becoming an old curdmudgeon and simply hate new things but I liked the old layout. While the new is certainly not terrible as some, new reddit comes to mind, it doesn't improve readability for me.
Click to expand...
The old layout resembled very much a well-printed paper document. I liked that, it was easily-readable and looked very professional imho.
The new layout reminds more of smartphone/tablet screens crowded with useless garbage, resulting in very small effective usable screen.
 
The new layout looks fine on a 24-inch screen. For a 13-15 inch laptop screen, it does get crowded, esp. if I adjust font size or other zooming for readability. If I want to actually study something, I wouldn't want to stare at my phone, and endlessly scroll back and forth.
 
The present Handbook makes NO reference to bsdconfig(8), needed for post-installation tasks, in particular adding included packages, without access to network, from DVD1 - or proper indexed access to main repositories for that matter.

(I'm writing up how broken package installation from DVD1 is at the moment, but a handbook section on bsdconfig would have saved me quite some time and I'm not a newbie.)

Also +1 for black on white (or v.v.) for readability from another with aging eyes, using a phone and 14" laptop.
 
You must log in or register to reply here.
Back
Top