freebsd-src
freebsd-src copied to clipboard
freebsd
hier.7: wordsmithing, typos, and additions
These are mostly minor (e.g. typos, consistency) nits together I feel really polish hier(7) and improve the immediate accessibility of the freebsd manual to new users.
Less minor nits:
Description: substitute layout for index for first glance reading comprehension. I tested this on completely irrelevant people and am proud. But is it sane to remove the keyword "layout"?
Fill in basic structures of </usr/local/>. I assume everyone never did it on purpose, but is it a good time?
Unfold longest sysroot and local entries a little. This is much more legible, but not seamless.
Fix my earlier mistakes, apologies.
a portion of it being more opinionated than necessary.
Sir, would you be willing to teach me more about this? I am trying to polish rust off beautiful ancient machinery, not engrave it.
Edit: like ostensibly everyone else here that's around my age, I am attracted to this project for it's consistency. Everything I've proposed in this project has been, from my opinion, janitorial intern tier, operations to contribute to that. "Opinionated" in this case is almost as undesirable, to me, as "incorrect". Sorry for wordy explanation, I don't want to be misunderstood. I admire what you guys are doing and want to learn to help better.
a portion of it being more opinionated than necessary.
Sir, would you be willing to teach me more about this? I am trying to polish rust off beautiful ancient machinery, not engrave it.
Edit: like ostensibly everyone else here that's around my age, I am attracted to this project for it's consistency. Everything I've proposed in this project has been, from my opinion, janitorial intern tier, operations to contribute to that. "Opinionated" in this case is almost as undesirable, to me, as "incorrect". Sorry for wordy explanation, I don't want to be misunderstood. I admire what you guys are doing and want to learn to help better.
I remember that someone did a "wordsmithing/clarity" pass at the whole page, and it got a couple replies basically saying "you didn't actually improve anything, you just changed the wording". So it was "opinionated" in the sense that an obvious clarification to one person was neutral, or a demotion, to another.
This will always be the struggle with documentation. Language is always imperfect, incomplete, imprecise. Plus we have a very diverse audience here with different experience/backgrounds with English. The same goes with code for that matter, as we can always debate the exact expression of a particular idea.
As I stated, I do see the majority of changes you have made here as improvements, and you are taking a holistic look at the page, not just making random nit-picks. You are obviously able to look at these things with fine-grained detail, and are willing and able to accept feedback, which combined are the first hurdle of contributing to this project. The second hurdle is, IMO, "don't worry so much". One could spend a long, long time polishing a document to "perfection", or with the same time they could write something new and substantial that is "great" in quality. This is the line between pragmatic and opinionated improvements, as I have observed.
Take it from someone who was, for a while, the youngster around here.
For mfc to 14:
- /home/ entry needs moved to /usr/home/
- save-entropy(8) needs to be backported, we don't have it on fx14p6 (might be in stable?)
For mfc to 13 (in addition to above):
- opie needs re-added
- Maybe something else?
I would do this myself but I see that I'm not understanding enough. If I just prepare two hier.7's in vi on the stable branches, and submit PR, the commits will be incorrect right? git switch, cherrypick, vi, commit amend, push, pr?
