Event: Halifax Hackathon 202606 Sponsored by: The FreeBSD Foundation
Details
Details
Diff Detail
Diff Detail
- Lint
Lint Skipped - Unit
Tests Skipped
Event Timeline
Comment Actions
Does i386 kernel even start when boot from loader.efi? I remember that i386 kernel always assumes that BIOS services are present, and cannot work otherwise at all.
Comment Actions
Yeah we don't have i386 UEFI support (IIRC there were some WIP patches that were never merged). But i386 does have the sysctl and always reports machdep.bootmethod: BIOS
Comment Actions
Maybe this text?
AArch64 (arm64) FreeBSD systems use the UEFI boot loader. 32-bit x86 systems (i386) use the BIOS boot loader. To determine which boot loader to update on your 64-bit x86 system (amd64), run the following command:
Comment Actions
LGTM but please remove "FreeBSD", this document is obviously about FreeBSD and when I have had my friends unrelated to FreeBSD review my drafts, they have told me that the constant reiteration makes it more tedious. Related: https://reviews.freebsd.org/D57606
Comment Actions
Updating this in two identical files is bad. Asciidoctor has native redirects, I have proposed using these here, mostly just to brief our team that it's this easy: https://reviews.freebsd.org/D57792
Comment Actions
Of course this doc is about FreeBSD, but I don't think this is excessive. It is useful to clarify that we are talking about FreeBSD's boot methods, not implying that a given CPU arch in general uses a given method.
Comment Actions
Of course this doc is about FreeBSD, but I don't think this is excessive. It is useful to clarify that we are talking about FreeBSD's boot methods, not implying that a given CPU arch in general uses a given method.
This is the logic that ends up with FreeBSD in every third sentence everywhere in our docs, because the OS docs are nearly always strictly about the OS since its a platform and can be implemented nearly infinite ways. No one will be confused by this, and it adds extra, irrelevant work required to read the docs. This type of doc should be kept as simple as possible. This is a procedural doc, it's not a reference manual.
| website/content/en/releases/15.1R/upgrading.adoc | ||
|---|---|---|
| 180 | We would be better off without this second line. The thing about this type of doc, is that if you waste any words, the reader starts skipping stuff. I watch people read these aloud on YouTube. While you are focusing on hardcore engineering that is over my head, I am focusing very deeply and intently on this. | |
Comment Actions
Perhaps I have never explained it well enough, but technical writing is like code optimization. You have to be careful to build what you actually need, and not the stuff around it. Premature optimization goes right off the rails and actually can ruin performance. Similarly, extra ideas spend the reader's clever bits and they can easily get overwhelmed. Senior colleagues like you know effectively everything, but we need give them only the answer that the doc is after. Every word has a concept backing it, and what makes the doc not-abrasive is that it sufficiently explains exactly what they're looking for, and they don't need to rest after reading it. Maybe I'm still not explaining it well enough, sorry for that.
Comment Actions
@ziaee I understand the need for, and share your desire for, correct and concise documentation. Give this one a look.
| website/content/en/releases/15.1R/upgrading.adoc | ||
|---|---|---|
| 180 | I thought about this a little more, i386 is not supported in this release. They can still compile from source, but if they do, then this entire doc does not apply to them. | |
| 181 | absolutely meaningless nit: The style in our adoc files is that sentences have no line breaks. Personally, I don't like this, but it's what we do. | |
| website/content/en/releases/15.1R/upgrading.adoc | ||
|---|---|---|
| 180 | Well, they still need to update their loader and this section is still applicable. If we (can) assume that this doc is for tier-1 architectures only we could just have "Otherwise, run the ..." Or, `On x86_64 (amd64) systems, run ..." | |
| website/content/en/releases/15.1R/upgrading.adoc | ||
|---|---|---|
| 180 | I was thinking along the lines of the latter, that this doc is strictly for upgrading existing systems to 15.1-RELEASE. But, we consistently use the terms AArch64 and AMD64, so I'd like to just use that, since they would have gotten far enough to have a system that they are upgrading if they didn't know that. Even the downloads page only says those terms. AArch64 systems always use the UEFI boot loader. To determine which boot loader to update on AMD64 systems, run the following command:" | |
Comment Actions
Well, they still need to update their loader and this section is still applicable.
How about we put this in the manpage and/or the handbook? If people are searching through docs that say at the top that they do not apply to the reader's use case, I have failed entirely.