DOCS-1092: ZFS Docs Expansion Review

- Correct spelling, grammar, Markdown syntax.
- Add missing cross-references
- Rework broken text that was Sphinx guide-specific
- Integrate cache and log device instructions in the pools article and remove standalone article.

content/en/hub/additional-topics/reference/dataset-options.md

@@ -1,12 +1,11 @@
 ---
 title: "ZFS Dataset Reference Information"
-description: "ZFS Dataset Reference Information" 
 tags: ["ZFS"]
 ---
 
-Some settings are only available in **ADVANCED MODE**. To see these settings, either click the **ADVANCED MODE** button, or configure the system to always display advanced settings by enabling the **Show advanced fields by default** option in **System** > **Advanced**.
+Some dataset options are only available in **ADVANCED MODE**. To see these settings, either click the **ADVANCED MODE** button or configure the system to always display advanced settings by enabling the **Show advanced fields by default** option in **System** > **Advanced**.
 
-### Dataset Options
+## Dataset Options
 
 | Setting                                          | Value               | Advanced Mode | Description |
 |--------------------------------------------------|---------------------|---------------|---------------|
@@ -33,35 +32,33 @@ Some settings are only available in **ADVANCED MODE**. To see these settings, ei
 | Case Sensitivity                                 | drop-down menu      |               | Choices are *sensitive* (default, assumes filenames are case sensitive), *insensitive* (assumes filenames are not case sensitive), or *mixed* (understands both types of filenames). This can only be set when creating a new dataset.   |
 | Share Type                                       | drop-down menu      |               | Select the type of share that will be used on the dataset. Choose between *Generic* for most sharing options or *SMB* for a SMB share. Choosing SMB sets the `ACL Mode` to *Restricted* and `Case Sensitivity` to *Insensitive*. This field is only available when creating a new dataset.  |
 
-
-
 After a dataset is created it appears in **Storage** > **Pools**. Click <i class="fas fa-ellipsis-v" aria-hidden="true" title="Options"></i>&nbsp (Options) on an existing dataset to configure these options:
 
 **Add Dataset**: create a nested dataset, or a dataset within a dataset.
 
 **Add Zvol**: add a zvol to the dataset. Refer to Adding Zvols for more information about zvols.
 
-**Edit Options**: edit the pool properties described in Table 8.2.8. Note that `Dataset Name` and `Case Sensitivity` are read-only as they cannot be edited after dataset creation.
+**Edit Options**: edit the dataset properties as described in the table above. Note that `Dataset Name` and `Case Sensitivity` are read-only as they cannot be edited after dataset creation.
 
-**Edit Permissions**: refer to Setting Permissions for more information about permissions.
+**Edit Permissions**: change the basic dataset access rules. <!--Add reference/link to dataset permissions content when it is added. -->
+
+**Edit ACL**: see [Managing Access Control Lists](/hub/tasks/advanced/editingacls/) for details about modifying an Access Control List (ACL).
 
 {{% alert title=Warning color=warning %}}
 Removing a dataset is a permanent action and results in data loss!
 {{% /alert %}}
 
-**Edit ACL**: see ACL Management for details about modifying an Access Control List (ACL).
-
 **Delete Dataset**: removes the dataset, snapshots of that dataset, and any objects stored within the dataset. To remove the dataset, set `Confirm`, click `DELETE DATASET`, verify that the correct dataset to be deleted has been chosen by entering the dataset name, and click `DELETE`. When the dataset has active shares or is still being used by other parts of the system, the dialog shows what is still using it and allows forcing the deletion anyway. **Caution**: forcing the deletion of an in-use dataset can cause data loss or other problems.
 
 **Promote Dataset**: only appears on clones. When a clone is promoted, the origin filesystem becomes a clone of the clone making it possible to destroy the filesystem that the clone was created from. Otherwise, a clone cannot be deleted while the origin filesystem exists.
 
 **Create Snapshot**: create a one-time snapshot. A dialog opens to name the snapshot. Options to include child datasets in the snapshot and synchronize with VMware can also be shown. To schedule snapshot creation, use Periodic Snapshot Tasks.
 
-### DeDuplication
+## DeDuplication
 
 Deduplication is often considered when using a group of very similar virtual machine images. However, other features of ZFS can provide dedup-like functionality more efficiently. For example, create a dataset for a standard VM, then clone a snapshot of that dataset for other VMs. Only the difference between each created VM and the main dataset are saved, giving the effect of deduplication without the overhead.
 
-### Compression
+## Compression
 
 When selecting a compression type, balancing performance with the amount of disk space saved by compression is recommended. Compression is transparent to the client and applications as ZFS automatically compresses data as it is written to a compressed dataset or zvol and automatically decompresses that data as it is read. These compression algorithms are supported:
 

content/en/hub/initial-setup/storage/hotspare-poolextension.md

@@ -1,23 +1,22 @@
 ---
 title: "Hot Spares and Pool Extension"
-description: "Adding spare devices and Extending a Pool" 
+description: "Adding spare devices and extending a pool."
 tags: ["ZFS","zpool"]
 ---
 
-
-### Adding Spare Devices
+## Adding Spare Devices
 
 ZFS provides the ability to have “hot” spares. These are drives that are connected to a pool, but not in use. If the pool experiences the failure of a data drive, the system uses the hot spare as a temporary replacement. If the failed drive is replaced with a new drive, the hot spare drive is no longer needed and reverts to being a hot spare. If the failed drive is detached from the pool, the spare is promoted to a full member of the pool.
 
-Hot spares can be added to a pool during or after creation. On TrueNAS®, hot spare actions are implemented by [zfsd(8)](https://www.freebsd.org/cgi/man.cgi?query=zfsd).
+Hot spares can be added to a pool during or after creation. On TrueNAS, hot spare actions are implemented by [zfsd(8)](https://www.freebsd.org/cgi/man.cgi?query=zfsd).
 
-To add a spare during pool creation, click the `Add Spare` button. Select the disk from `Available Disks` and use the <i class="fas fa-arrow-right" aria-hidden="true" title="Right Arrow"></i>&nbsp (right arrow) next to `Spare VDev` to add it to the section.
+To add a spare during pool creation, click `Add Spare`. Select the disk from `Available Disks` and use the <i class="fas fa-arrow-right" aria-hidden="true" title="Right Arrow"></i>&nbsp (right arrow) next to `Spare VDev` to add it to the section.
 
-To add a device to an existing pool, Extend that pool.
+To add a device to an existing pool, extend that pool.
 
-### Extending a Pool
+## Extending a Pool
 
-To increase the capacity of an existing pool, click the pool name, <i class="fas fa-cog" aria-hidden="true" title="Settings"></i>&nbsp (Settings) (Settings), then **Extend**.
+To increase the capacity of an existing pool, click the pool name, <i class="fas fa-cog" aria-hidden="true" title="Settings"></i>&nbsp (Settings), then **Extend**.
 
 If the existing pool is encrypted, an additional warning message shows a reminder that **extending a pool resets the passphrase and recovery key**. Extending an encrypted pool opens a dialog to download the new encryption key file. Remember to use the Encryption Operations to set a new passphrase and create a new recovery key file.
 

content/en/hub/initial-setup/storage/pools.md

@@ -8,7 +8,7 @@ tags: ["ZFS", "zpool"]
 Perhaps the most important part about TrueNAS is the ability to efficiently store and share large amounts of data.
 The way this is accomplished is through setting up [ZFS Pools](https://en.wikipedia.org/wiki/ZFS#Data_structures:_Pools,_datasets_and_volumes "ZFS Pools Wikipedia").
 
-### Creating a new Pool
+## Creating a new Pool
 
 To set up a pool in TrueNAS, go to **Storage > Pools** and click *ADD*.
 
@@ -45,24 +45,39 @@ Create a new pool for the different layout.
 For example, "pool1" has a data vdev in a *mirror* layout, so create "pool2" for any *raid-z* vdevs.
 {{% /alert %}}
 
-If desired, a cache, log, and spare vdev can be added by clicking *ADD CACHE*, *ADD LOG*, and *ADD SPARE*, respectively.
-When ready to proceed with the desired vdevs, click *CREATE*.
-
 <img src="/images/pools-vdevs.png">
-<br><br>
+<br>
+
+### Adding Cache or Log Devices
+
+An SSD cache or log device can be added during or after pool creation to improve performance of the pool under specific use cases. Before adding a cache or log device, refer to the [ZFS Primer](/hub/additional-topics/reference/zfs-references/) to determine if the system will benefit or suffer from the addition of the device.
+
+To add a Cache or Log device during pool creation, click the **Add Cache** or **Add Log** button. Select the disk from `Available Disks` and use the <i class="fas fa-arrow-right" aria-hidden="true" title="Right Arrow"></i>&nbsp (right arrow) next to `Cache VDev` or `Log VDev` to add it to that section.
+
+To add to an existing pool, extend that pool and follow the same procedure.
+
+#### Advanced Options
+
+| Setting            | Value          | Advanced Mode | Description |
+| Block size         | drop-down menu | ✓             | The default is *Inherit*, other options include, *4KiB*, *8KiB*, *16KiB*, *32KiB*, *64KiB*, *128KiB*|
+
+#### Removing Cache or Log Devices
+
+Cache or log devices can be removed by going to **Storage** > **Pools**. Choose the desired pool and click <i class="fas fa-cog" aria-hidden="true" title="Settings"></i>&nbsp (Settings) > **Status**. Choose the log or cache device to remove, then click <i class="fas fa-ellipsis-v" aria-hidden="true" title="Options"></i>&nbsp (Options) > **Remove**.
+
+## Importing a Pool
 
-### Importing a Pool
-A pool that has been exported and disconnected from the system can be reconnected with **Storage** > **Pools** > **Add**, then selecting **Import an existing pool**. This works for pools that were exported/disconnected from the current system, created on another system, or to reconnect a pool after reinstalling the TrueNAS® system.
+A pool that has been exported and disconnected from the system can be reconnected with **Storage** > **Pools** > **Add**, then selecting **Import an existing pool**. This works for pools that were exported/disconnected from the current system, created on another system, or to reconnect a pool after reinstalling the TrueNAS system.
 
-When physically installing ZFS pool disks from another system, use the `zpool export poolname` command at the command line or a web interface equivalent to export the pool on that system. Then shut it down and connect the drives to the TrueNAS® system. This prevents an *“in use by another machine”* error during the import to TrueNAS®.
+When physically installing ZFS pool disks from another system, use the `zpool export poolname` command at the command line or a web interface equivalent to export the pool on that system. Then shut it down and connect the drives to the TrueNAS system. This prevents an *“in use by another machine”* error during the import to TrueNAS.
 
 Existing ZFS pools can be imported by clicking **Storage** > **Pools** and **ADD**. Select **Import an existing pool**, then click **NEXT**
 
 <img src="/images/storage-pools-import.png" width='700px'>
 <br><br>
 
 If the Pool is not encrypted with GELI encryption, click **No, continue with import** then **NEXT**.
-If the Pool is encrypted see below for those instructions.
+If the Pool is encrypted, see the instructions below for decrypting the disk.
 
 <img src="/images/storage-pools-import-no-encryption.png" width='700px'>
 <br><br>
@@ -78,14 +93,13 @@ Use the `Disks` dropdown menu to select the disks to decrypt. Click **Browse** t
 <img src="/images/storage-pools-add-decrypt.png" width='700px'>
 <br><br>
 
-Danger
 {{% alert title=Warning color=warning %}}
-The encryption key file and passphrase are required to decrypt the pool. If the pool cannot be decrypted, it cannot be re-imported after a failed upgrade or lost configuration. This means it is very important to save a copy of the key and to remember the passphrase that was configured for the key. Refer to Managing Encrypted Pools for instructions on managing keys.
+The encryption key file and passphrase are required to decrypt the pool. If the pool cannot be decrypted, it cannot be re-imported after a failed upgrade or lost configuration. This means it is very important to save a copy of the key and to remember the passphrase that was configured for the key. Refer to the [Encryption article](/hub/initial-setup/storage/encryption/) for instructions on managing keys.
 {{% /alert %}}
 
 Select the pool to import and confirm the settings. Click **IMPORT** to finish the process.
 
 {{% pageinfo %}}
-For security reasons, encrypted pool keys are not saved in a configuration backup file. When TrueNAS® has been installed to a new device and a saved configuration file restored to it, the keys for encrypted disks will not be present, and the system will not request them. To correct this, export the encrypted pool with <i class="fas fa-pen" aria-hidden="true" title="Pen"></i>&nbsp; (Configure) > **Export/Disconnect**, making sure that Destroy data on this pool? is not set. Then import the pool again. During the import, the encryption keys can be entered as described above.
+For security reasons, encrypted pool keys are not saved in a configuration backup file. When TrueNAS has been installed to a new device and a saved configuration file restored to it, the keys for encrypted disks will not be present, and the system will not request them. To correct this, export the encrypted pool with <i class="fas fa-pen" aria-hidden="true" title="Pen"></i>&nbsp; (Configure) > **Export/Disconnect**, making sure that **Destroy data on this pool?** is not set. Then import the pool again. During the import, the encryption keys can be entered as described above.
 {{% /pageinfo %}}