Additional changes to the ZFS handbook chapter

[allanjude]

Summary

• Some minor language improvements
• New section on selecting vdev type to use
• Improved clone section
• More and better examples

[allanjude]

Missed igor run on last minute change

[bjk]

[inline]

en_US.ISO8859-1/books/handbook/zfs/chapter.xml

2304

Clones, plural.

2305

"indefinitely"

2331

"counted" may have undesired connotations here. The traditional idiom involves "accounted", but I don't immediately see a way for that to work here. (The current text is probably okay if we don't find anything better.)

3132

comma splice

[bcr]

Some comments from me inside... Language nits from a non-native speaker.

en_US.ISO8859-1/books/handbook/zfs/chapter.xml

2331

I think we should avoid these braces. Maybe something like: "... because they are still being used by the first file system, and snapshots that belong to it."

2392

it can be destroyed as well now.
My english teacher would say that each time we didn't put the tense at the end (or the beginning) of the sentence. A minor thing...

[wblock]

en_US.ISO8859-1/books/handbook/zfs/chapter.xml

175

This is redundant. Actually, I'm pretty sure it was this way and I removed the "like in this example" part.

469–470

This sentence is somewhat passive. How about just "Do not disable checksums!"

476

Combine and simplify:

"Many features will not work properly without checksums, and there is no noticeable performance improvement gained by disabling them."

726

Good!

1943

This is a whitespace change.

2300

"more like" is vague.

2300–2433

This sentence is really complicated.

"Clones are typically used for experimenting with a dataset while preserving the original."

2301

"be powerful" is weird, and "in the case of" is wordy.

"Clones can also be useful for databases, ..."

2302

"can" is not needed.

2303

"Similar to snapshots, a clone shares unmodified blocks with the <literal>origin</literal> snapshot from which it was created."

Should "origin" be literal, or emphasis?

2305

Break the sentence here.

"This conserves space, and the clone only grows when it is modified."

2307

This is also pretty complicated.

"Clones can be kept indefinitely. If the clone achieves the desired result, it can be promoted to the parent dataset. The original file system can them be destroyed."

2331

Agreed. "snapshots" means any number of them, including 1. Also agreed that "its" is nonspecific. The comma after "system," is not needed.

2331

Maybe "The way that space usage is recorded..."?

2334

"but the blocks that are owned by the parent and child change."

2338

"The connection is recorded in the <literal>origin</literal> property."

2341

The multiple if/thens make this sentence confusing.

"The dependency between the clone and the original dataset is reversed by <command>zfs promote</command>. The original dataset becomes the clone."

2343

Break sentence at "blank".

2344

Active, not passive:

s/will now point/now points/

2370

Delete "some".

2371

"the state wanted by the administrator. The old dataset is obsolete"

2374

s/by/with/

2390

"Any changes made the original dataset after the snapshot the clone was based off of have been destroyed."

That is... complicated.

"The clone is based on a snapshot. Any changes made to the original dataset after that snapshot was created will be destroyed."

2392

"Now" is already used at the beginning of the sentence, but I'd change the plurals:

"Now that there are no other datasets depending on the snapshot, it can be destroyed as well."

3095

"Choosing the type of vdevs for constructing a pool requires..."

3104

Too many "since"s in this paragraph.

s/since/because/ here.

3106

Break the sentence:

"Mirrors provide good redundancy. Each disk in a vdev contains a complete copy of the data..."

3108

Break the sentence:
"The downside to mirrors is that they provide the worst capacity. Each mirror vdev, no matter how many disks it contains..."

3111

<acronym> on RAID.

3115

<acronym>

3116

<acronym>

3118

<acronym> on RAID-Z2, and s/Z3/-Z3/

3119

"concurrent" is a little unclear. "two failed disks" and "three failed disks" is clearer.

3120

"of redundancy" is itself redundant.

3121

Remove "the level of" and "the amount of".

3122

<acronym>

3126

<acronym> in the rest of the paragraph for RAID

3131

"more separate" is weird and unclear. Just "more" is probably good.

3275

sysctl should have markup, probably &man.sysctl.8;

<acronym> on ZFS.

3277

"unless it has no redundancy."

3703

This should probably be a table.

4162–4163

Should be markup on "copies".

[bcr]

I added Dru Lavigne now that she has access to Phabricator. She wanted to do an editorial review for the chapter (when she finds the time) and might have comments on these changes as well.

[allanjude]

Address some feedback

en_US.ISO8859-1/books/handbook/zfs/chapter.xml

2303

In this case 'origin' is the name of a ZFS property, indicating the parent dataset. You read it with 'zfs get origin <dataset>'

2334

This reads like the blocks are being changed, which is not the case. It is just the accounting that changes.

3111

Should these be treated as whitespace changes? I imagine it would be easier on the translators if I didn't mix bulk markup changes with content changes.

[allanjude]

Update with feedback

[allanjude]

Undo accidental whitespace change

[delphij]

en_US.ISO8859-1/books/handbook/zfs/chapter.xml

190

It's probably worth replacing this with lz4 and leave gzip for those who know what they are doing.

242

It would be worth mentioning why one wants to do it (e.g. for single disk pool, additional copies of data would provide more redundancy; in the case there is bad block on the hard drive, this gives more opportunity to recover data).

272

One do not really need to destroy individual datasets when destroying the whole pool -- do we really want to demonstrate how to destroy the pool here?

312

Similar -- we probably want to tell the users to use compression=lz4 instead.

341

Should we mention that rollback would destroy all data that is newer than the snapshot here?

361

Since we have already created a symlink, do we still want to set the mountpoint? Setting the property may confuse replica (zfs send -R would send these properties) and cause undesirable results.

512

I think we should also mention the periodic zpool scrub tasks. It's part of maintaining a storage pool, just like RAID card's "patrol scanning".

602

Should we move the description of RAID-Z2 earlier? It could be confusing for readers as they have no idea what RAID-Z2 is at this point, even with a link.

1306

This doesn't seem right. These devices can be used (open for write) after export but zfs would give a warning if they are being used to create additional pool.

1408

The current ZFS code would say:

async_destroy
empty_bpobj
lz4_compress
multi_vdev_crash_dump
spacemap_histogram
enabled_txg
hole_birth
extensible_dataset
embedded_data
bookmarks
filesystem_limits
large_blocks

1472

and some features, for instance large blocks, must not be used on the boot pool.

2863

Why it's 125% not 133%? (Assuming compressed data is 1-25% = 75% of old size, we have S=1/(75%)=4/3).

2866

Compression does require additional memory (to stash compressed data before writing) but it's not as much as deduplication does.

2871

v5000 should not be mentioned anywhere because it's not a meaningful number. Maybe describe this as "feature flags" or just "With the introduction of ..lz4.. compression, it is possible...?

2887

Personally I would prefer using 'zfs list -o name,used,compressratio,compression,logicalused ...' instead. Just my $0.02.

2939

perhaps target *dataset* here?

3699

This information is obsolete, please remove.

See: http://blog.delphix.com/matt/2014/06/06/zfs-stripe-width/

4090

There is no "version 5000", 5000 is only a magic number and is not intended to be visible by user.

[wblock]

en_US.ISO8859-1/books/handbook/zfs/chapter.xml

147

Too many sentences starting with "The", and this can be reversed:

Deciding on a disk layout is the first step in creating a new <acronym>ZFS</acronym> pool.

148

This sentence is a little unclear. It's trying to say that choosing correctly is both complex and impossible to undo. Maybe:

Because there are many options and the choices cannot be changed after a pool has been created, it is important to take care when creating a pool.

2304

Maybe Phabricator helping, but this reads "how snapshots works". Fix that, and simplify:

Similar to snapshots, clones share

3096

s/construct/constructing/

3097

Complex sentence:

"Choosing the type"
"constructing a pool"
"requires deciding"

Maybe rearrange and rewrite these two sentences:

The main considerations for a pool are redundancy, capacity, and performance.
These factors influence the choice of vdevs used to create a pool.

3111

I'd say no, this is not like a whitespace change. The point to separating out whitespace changes is so translators can avoid dealing with them at all--there is nothing in them to put in the translated version. New markup does need to be in the translated version.

[grahamperrin]

@carlavilla FYI