Convert ZFS chapter to active voice and remove weasel/unnecessary words

[bcr]

Summary

Convert many of the sentences in this chapter from passive to active voice. Example: "... a data error has been detected" (passive) vs. "detecting a data error" (active). In many cases, the sentences became shorter, but also easier to read and understand. In some instances, adding ZFS in places where the sentence would become too short.
Note to translators: In some cases, I merged a short sentence into the previous one to improve reading flow.

Remove weasel and unnecessary words that do not add any extra meaning to the sentence like: many, significantly, very, relatively, a number of, clearly, extremely, etc.

Test Plan

1. Apply the patch do a doc tree checkout
2. Build the handbook
3. Read the output

[bcr]

content/en/books/handbook/zfs/_index.adoc

2533

I changed it to /usr/bin and removed mentions of "the ports tree" in surrounding sentences.
I think we always assume that /bin/sh is used for shell scripts like this in the handbook. Otherwise, we'd have to mention something like "adapt to your shell syntax if necessary" to each example.
In this particular example, the loop is not really necessary for the gist of this example, but speeds things up.

[bcr]

Update including the lastest suggestions to the lower last part of the chapter.

[pauamma_gundo.com]

Mentioning it here to avoid repeating it a gazillion times: 1 sentence per line.

Not done yet for tonight but Chromium just crashed on me, and while it somehow restored the partial review when I restarted it, I don't count on that happening twice, no siree.

content/en/books/handbook/zfs/_index.adoc

2614

*ponders* To me, "the mountpoint where mounting the file system", looks like it's missing a large part of the sentence. I think "the mountpoint where to mount the file system" would be better.

Unrelatedly; is it "mountpoint" or "mount point"?

2628

This way, it sounds less like ordering the user around and more like offering options for their consideration.

2630–2634

To me, "upper size of" reads as "size of the upper part of". I would either keep "maximum" or, if you prefer "upper", use something like "upper limit of the size of.

2632

2633

2634

2639

Maybe add an explanation of how to check? I had a look into dmesg.boot on my laptop, which reports 512 bytes but given the above, it may be wrong. Is the best answer "look up the drive's spec sheet on the Internet"?

2643

"will use" or "may use", I think.

2646–2657

Since it's countable here, not mass. Taste.

2649

Taste, concision.

2651

Also, see above re "upper" vs "maximum".

2654

Taste, clarity, redundant spaces not after a full stop.

2655

Same as above

2657

See above upper vs. maximum. Also, spurious spaces.

2662

If you don't like "maximum" here, maybe "better" or "higher"?

2666–2667

2688–2689

Missing subject here.

2713

2716

Concision.

2717

I think this is what you meant. While there, I also used the term introduced above.

2726

First sentence redundant with above, but since this is a glossary, I would keep it anyway.

Unless it's the name+GUID pair that identifies the pool, I would s/and/or/ in the 2nd sentence and maybe add "either".

2729

Assuming a few vdevs allow spreading, not just a lot (however many that means).

What's the initial "a|" for? Index term?

2737

Hey, I wrote that! *toot toot*

[pauamma_gundo.com]

Aaaaaaaand done! (Split glossary to 1 sentence per line, please.)

content/en/books/handbook/zfs/_index.adoc

2740–2741

Last sentence should be a paragraph of its own. Not sure whether it's better here or at the start of the vdev type section.

2745

Clarity

2748

2750

Grammar

2752

Is that recommendation still valid?

2755

Maybe nitpicking, but if not deployed automagically, are they still *hot* spares?

2756

Spurious spaces, grammar, a lot vs. several.

2757

Maybe nitpicking, but I think "only"worked better than "alone" here. The cache device doesn't have other duties, but it may (I think) share these duties with other cache devices.

2760

"assert" doesn't look quite right. Maybe "ensure" or "guarantee"?

2762–2764

"There is always a transaction group in the open state" was better, I think. Your version confused me since I understood it as "a (given) transaction group remains in the open state forever".

2763

Taste.

2764

Or perhaps "a number of passes" if you mean it's unbounded or maybe large. Your call.

Also, check I didn't change the meaning of the description of successive passes.

2767

While here (maybe for a later scrub): "LRU" feels wrong here, since the ordering and the insertion of new objects both feel more like "MRU" to me.

2770

What's a DDT?

2773

See above for only vs. alone.

2779

Only one of each.

Also, "technically"?

2782

"most others"?

If you don't want "is mounted", perhaps "the kernel mounts a ZFS file system"?

2785

IIRC, there's no longer any such thing in FreeBSD as a block device.

Also, "a lot of the same features" as what? Datasets?

2788–2789

Unsplit sentence here and on next line while splitting into 1-sentence lines?

2789

I don't understand what you mean by "Also mark snapshots with a <<zfs-zfs-snapshot,hold>>." Is that an order to the user or an option available to them?

Ditto for "Take snapshots on volumes, clone, or roll back to them, but not mount independently."

2792

"a snapshot" or "snapshots". (Also, isn't most or all of this also covered earlier? Maybe link there instead of repeating it and risking eventual inconsistency.)

2795

Duplicates earlier material better linked to?

2800

Isn't it strongly discouraged rather than merely "not recommended"?

2806

Arguably very nitpicky here, but crabs gotta crab.

2815

Why the initial caps in "File System" and "Volume"?

2818

Clarity, concision, spurious spaces.

2824

"a|"?

2828

Taste.

2832

Word choice.

2836

Contrast with "Quotas" above?

2845

What I think you mean.

2847

By "audio logs", do you mean sound files specifically, audi*t* logs, or generic (potentially) huge files in general?

2850

Grammar, word choice, spurious spaces.

2858

What does the first sentence mean?

2861

Word choice, clarity.

2864

Grammar, clarity, taste.

[bcr]

Yet another update addressing some of @pauamma_gundo.com's comments.

[bcr]

Update with some of my own replies.

content/en/books/handbook/zfs/_index.adoc

2740–2741

I removed it from here and moved it into the vdev Types section above.

2752

Not sure, but I think we need to do a separate technical review of the chapter with all the new stuff that came in OpenZFS 2.0.

2757

That would contradict the sentence "Mirroring cache devices is impossible".

[pauamma_gundo.com]

I'll have another look at the whole thing, but it will likely be a few days before I can.

content/en/books/handbook/zfs/_index.adoc

2757

Now I'm confused about the whole paragraph. I assumed "Adding a cache vdev to a pool will add the storage of the cache to the <<zfs-term-l2arc,L2ARC>>" meant you can have several vdevs in the L2ARC, and that's why I suggested "only" (as in, "L2ARC doesn't store any other data") instead of "alone" (which to me means "this vdev and no other").

[bcr]

Reply with confirmation about the L2ARC vdevs question.

content/en/books/handbook/zfs/_index.adoc

2757

it is possible to have several L2ARC vdev cache devices (striped, not mirrored), see:
https://www.truenas.com/docs/references/l2arc/

I'll change it back to only then.

[bcr]

Change an instance of "alone" to "only" in the L2ARC description to not confuse people about adding multiple devices there.

[pauamma_gundo.com]

As far as I'm concerned, I think you can go ahead and commit at your discretion after this round of (very minor) suggestions. Getting to diminishing returns here.

content/en/books/handbook/zfs/_index.adoc

6

Is "designs" the best word here? I'm tempted to say "file systems" but that's only a part of what ZFS does and its integration of several layers is its major strength, so perhaps "storage subsystem software", for all that it's a mouthful?

52–54

Difference between "ditto" and "mirror"?

68

306–308

368

Or "a disk being"

869

1354

1599

1695–1696

1737

2792

Still needs number agreement.

[bcr]

Alright, I incorporated these last feedback items. I'm going to commit this shortly.
Thanks to all reviewers, your feedback and suggestions helped a lot in improving the text!