handbook: Misc fixes to Introduction chapter

[trasz]

Summary

This improves wording in many places, adds links to {dev-model}
and {contributing}, and makes it more clear that we don't just
look for C developers. Most of those fixes were contributed by Pau.

[pauamma_gundo.com]

documentation/content/en/books/handbook/introduction/_index.adoc

127

Is this still true as stated? ISTR Linux is now an option for some of their offer, in which case "is available with" would be more correct.

144–153

To make it more obvious it's the replacement that's thus designed, not the large enterprise routers. (If still not obvious enough, may move "designed to run on standard PC hardware" next to "replacement" and wrap it in ().

146

Or maybe "beautiful looks" instead. Your call.

149

150

151

212–213

I'd link to https://docs.freebsd.org/en/books/dev-model/ from here.

212–215

To me, "on the lookout" means actively looking for them, instead of being willing and welcoming if they come on their own. Is that what you mean?

Also, if you (FSVO "you") want more documentors, mention that explicitely, with a parallel pointer to freebsd-doc@.

255–257

Same comment as above re documenters. Maybe also on the previous line.

272–273

Is there a macro for the "as of" date? Without an easy way for readers to know that as well, the stat is pointless IMO.

300

Since that URL is for all documents. (Also, perhaps make /en explicit instead of relying on the redirection, if only as a hint for translators to use their own language if they think enough is translated and current? Or do they already do that as a matter of course without needing the prompt?)

[trasz]

documentation/content/en/books/handbook/introduction/_index.adoc

127

I think it is, the Linux one is called TrueNAS Scale, it's a separate product line.

146

I think "looks" sounds more... idiomatic?

212–215

Can we hold off with this (and a similar chunk below) for now? This whole section is written as if ports and documentation didn't exist, ie it's a larger change.

272–273

The number of ports doesn't change all that much though. How about now?

I've also split the part about packages into separate paragraph; I feel this reads better.

300

This sounds a bit weird to me, tbh. It's not like we have multiple copies of the Handbook there. Perhaps just "up to date documentation"?

Do you know if the redirection is always to "en", or does it depend on browser settings?

[trasz]

Fixes, mostly from Pau.

[trasz]

Rebase (the mechanical change got committed) and reword
things a bit to make them bit less src-centric; point
at {contributing} instead.

[debdrup]

I think this is ready to go now?

[pauamma_gundo.com]

Other than the few nits above, LGTM too.

documentation/content/en/books/handbook/introduction/_index.adoc

128

Since you're touching this file: I would change "including routers, switches, security, and networking appliances" to either "including routers, switches, security appliances, and networking appliances" or maybe "including routers, switches, and security and networking appliances". But that's arguably my taste speaking.

146

I just checked with an English speaker more tuned to US culture than me, who confirms my impression that of "beautiful looks" and "a beautiful look", the former is more often used of a person (more often than not a woman) and the latter of an object (including a software UI). So on second thought, "a beautiful look" is the appropriate one here.

212–215

Sure. You're the one with the commit bit. :-)

272–273

WFM.

300

This sounds a bit weird to me, tbh. It's not like we have multiple copies of the Handbook there. Perhaps just "up to date documentation"?

WFM.

Do you know if the redirection is always to "en", or does it depend on browser settings?

I just moved French to the top of my Chromium languages list (English was there before), and https://docs.freebsd.org/ still redirected me to https://docs.freebsd.org/en/, so I guess the former.

[trasz]

Few more nits - most from Pau, but there's also two grammar fixes
I've noticed.

[debdrup]

I think this is ready to land now? So far as I can see everything's been addressed and a one-over didn't make anything else stand out.

[pauamma_gundo.com]

In D34100#775605, @debdrup wrote:

I think this is ready to land now? So far as I can see everything's been addressed and a one-over didn't make anything else stand out.

LGTM as well.