various small docs improvements (#5059)

docs/the_nimbus_book/src/hardware.md

@@ -9,6 +9,9 @@ The recommended system requirements for running the Nimbus beacon node are:
 | Disk space | 200GB |
 | Network    | Reliable broadband |
 
+!!! note
+    While the consensus client will work with a classic, spinning, hard disks, if you plan to run an execution client make sure you use an SSD, either SATA or NVMe.
+
 
 ### Execution client
 

docs/the_nimbus_book/src/keep-updated.md

@@ -54,12 +54,10 @@ Complete the upgrade by restarting the node!
 
 ## Urgency guidelines
 
-As of `v1.4.0`, releases are marked with the following tags:
+Nimbus releases are marked with the following tags:
 
 - `low-urgency`: update at your own convenience, sometime within our normal update cycle of two weeks
-
 - `medium-urgency`: may contain an important stability fix, it is better to update sooner rather than later
-
 - `high-urgency`: update as soon as you can, this is a critical update required for Nimbus to function correctly
 
 

docs/the_nimbus_book/src/metrics-pretty-pictures.md

@@ -1,6 +1,6 @@
 # Grafana and Prometheus
 
-In this page we'll cover how to use  Grafana and Prometheus to help you visualise important real-time metrics concerning your validator and/or beacon node.
+In this page we'll cover how to use Grafana and Prometheus to help you visualize important real-time metrics concerning your validator and/or beacon node.
 
 Prometheus is an open-source systems monitoring and alerting toolkit.
 It runs as a service on your computer and its job is to capture metrics.

docs/the_nimbus_book/src/migration.md

@@ -65,10 +65,6 @@ As part of the migration process, you need to stop your existing client and expo
 
     You will then find the `slashing-protection.json` file in your specified `/path/to/export_dir` folder.
 
-    !!! tip
-        To be extra sure that your validator has stopped, wait a few epochs and confirm that your validator has stopped attesting (check its recent history on [beaconcha.in](https://beaconcha.in/)).
-        Then go to [step 3](./migration.md#step-3---import-your-validator-keys-into-nimbus).
-
 === "Lighthouse"
 
     #### 1. Disable the Lighthouse validator client
@@ -101,10 +97,6 @@ As part of the migration process, you need to stop your existing client and expo
 
     This will export your history in the correct format to `slashing-protection.json`.
 
-    !!! tip
-        To be extra sure that your validator has stopped, wait a few epochs and confirm that your validator has stopped attesting (check its recent history on [beaconcha.in](https://beaconcha.in/)).
-        Then go to [step 3](./migration.md#step-3---import-your-validator-keys-into-nimbus).
-
 === "Teku"
 
     #### 1. Disable Teku
@@ -132,10 +124,6 @@ As part of the migration process, you need to stop your existing client and expo
     - `--data-path` specifies the location of the Teku data directory.
     - `--to` specifies the file to export the slashing-protection data to (in this case `/home/slash/slashing-protection.json`).
 
-    !!! tip
-        To be extra sure that your validator has stopped, wait a few epochs and confirm that your validator has stopped attesting (check its recent history on [beaconcha.in](https://beaconcha.in/)).
-        Then go to [step 3](./migration.md#step-3---import-your-validator-keys-into-nimbus).
-
 === "Nimbus"
 
     #### 1. Disable the Nimbus validator client
@@ -161,9 +149,9 @@ As part of the migration process, you need to stop your existing client and expo
 
     This will export your history in the correct format to `slashing-protection.json`.
 
-    !!! tip
-        To be extra sure that your validator has stopped, wait a few epochs and confirm that your validator has stopped attesting (check its recent history on [beaconcha.in](https://beaconcha.in/)).
-        Then go to [step 3](./migration.md#step-3---import-your-validator-keys-into-nimbus).
+!!! tip
+    To be extra sure that your validator has stopped, wait a few epochs and confirm that your validator has stopped attesting (check its recent history on [beaconcha.in](https://beaconcha.in/)).
+    Only after that, continue with the next step of this guide.
 
 
 ### 3. Import your validator key(s) into Nimbus

docs/the_nimbus_book/src/networking.md

@@ -127,7 +127,7 @@ To determine your private IP address, run the appropriate command for your OS:
 
 ## Check open ports on your connection
 
-Use [this tool](https://www.yougetsignal.com/tools/open-ports/) to check your external (public) IP address and detect open ports on your connection (Nimbus TCP and UDP ports are both set to `9000` by default).
+Use the [open ports tool](https://www.yougetsignal.com/tools/open-ports/) to check your external (public) IP address and detect open ports on your connection (Nimbus TCP and UDP ports are both set to `9000` by default).
 
 ## Reading the logs
 

docs/the_nimbus_book/src/start-syncing.md

@@ -1,12 +1,14 @@
 # Sync your node
 
 Before you can use your node, it needs to sync with the network.
-Syncing starts automatically when you start your node, and may take several days depending on the performance of your hardware.
-
-If you are planning to become a validator, you should ensure that your beacon node is [completely synced](./keep-an-eye.md#keep-track-of-your-syncing-progress) before submitting your deposit, or you might miss attestations and proposal duties until it has finished syncing.
+Syncing starts automatically when you start your node, and may take **several hours**, or even days, depending on the performance of your hardware.
 
 !!! tip
-    To get started more quickly, you can perform a [trusted node sync](./trusted-node-sync.md) instead - this requires access to a synced node or a third-party service.
+    To get started more quickly, you can perform a [trusted node sync](./trusted-node-sync.md) instead.
+    This requires access to a synced node or a third-party service.
+
+
+If you are planning to become a validator, you should ensure that your beacon node is [completely synced](./keep-an-eye.md#keep-track-of-your-syncing-progress) before submitting your deposit; otherwise, you might miss attestations, proposal duties and sync committee duties until it has finished syncing.
 
 !!! note
     You need need to run an execution client (**web3 provider**) together with the beacon node.
@@ -17,9 +19,8 @@ If you are planning to become a validator, you should ensure that your beacon no
 Using Nimbus, you can connect either to a testnet or mainnet.
 Mainnet is the main Ethereum network where real assets are at stake, while testnets are used by users and developers alike to test their node and setup before committing real assets.
 
-!!! tip
-    If this is the first time you're setting up your node, it is recommended you run it on a testnet first.
-    Later, when everything is working, you can easily switch to mainnet.
+If this is the first time you're setting up your node, it is recommended you run it on a testnet first.
+Later, when everything is working, you can easily switch to mainnet.
 
 === "Testnet"
 
@@ -59,7 +60,7 @@ INF 2020-12-01 11:26:36.285+00:00 Slot end                                   top
 ## Data directory
 
 While running, the beacon node will store chain data and other information its data directory, which by default is found in `build/data`.
-For more information, see the [data directory](./data-dir.md) guide.
+For more information, see the [data directory guide](./data-dir.md).
 
 ## Command line options
 
@@ -70,7 +71,7 @@ For example, to change the port to 9100, use:
 ./run-prater-beacon-node.sh --tcp-port=9100 --udp-port=9100
 ```
 
-To see a list of the command line options availabe to you, with descriptions, run:
+To see a list of the command line options available to you, with descriptions, run:
 
 ```
 ./build/nimbus_beacon_node --help

docs/the_nimbus_book/src/troubleshooting.md

@@ -160,5 +160,6 @@ See our page on [monitoring the health of your node](./health.md) for more.
 
 ### Trouble transferring data to/from USB3.0 SSDs
 
-We have seen reports of degraded performance when using several types of USB3.0 to SSD adapters or when using native USB3.0 disk drives. [This post](https://www.raspberrypi.org/forums/viewtopic.php?t=245931#p1501426) details why there is a difference in behaviour from models prior to Pi 4 and the recommended workaround.
+We have seen reports of degraded performance when using several types of USB3.0 to SSD adapters or when using native USB3.0 disk drives.
+[This post on RPi forums](https://www.raspberrypi.org/forums/viewtopic.php?t=245931#p1501426) details why there is a difference in behaviour from models prior to Pi 4 and the recommended workaround.
 

docs/the_nimbus_book/src/trusted-node-sync.md

@@ -1,13 +1,14 @@
 # Sync from a trusted node
 
-When you [start the beacon node](./quick-start.md) for the first time, it connects to the beacon chain network and starts syncing automatically — a process that can take **several hours** or even days.
+When you [start the beacon node](./quick-start.md) for the first time, it connects to the beacon chain network and starts syncing automatically — a process that can take **several hours or even days**.
 
 Trusted node sync allows you to get started more quickly by fetching a recent checkpoint from a trusted node — you can get started in **minutes** instead of hours or days.
 
 To use trusted node sync, you must have access to a node that you trust and that exposes the [Beacon API](./rest-api.md) (for example, a locally running backup node).
 Should this node, or your connection to it, be compromised, your node will not be able to detect whether or not it is being served false information.
 
-It is possible to use trusted node sync with a third-party API provider — see [here](trusted-node-sync.md#verify-you-synced-the-correct-chain) for how to verify that the chain you are given corresponds to the canonical chain at the time.
+It is possible to use trusted node sync with a third-party API provider.
+See [here](./trusted-node-sync.md#verify-you-synced-the-correct-chain) for how to verify that the chain you are given corresponds to the canonical chain at the time.
 
 !!! tip
     A list of community-operated checkpoint sync nodes can be found [here](https://eth-clients.github.io/checkpoint-sync-endpoints/).
@@ -22,7 +23,7 @@ It is possible to use trusted node sync with a third-party API provider — see
     Which means you would run the commands below with `--trusted-node-url=http://127.0.0.1:3500`
 
 !!! note
-    The path specified for `--data-dir` must be an empty directory as trusted node sync needs to be started from a fresh database.
+    The path specified for `--data-dir` must be an empty directory, as trusted node sync needs to be started from a fresh database.
 
 To start trusted node sync, run:
 
@@ -36,9 +37,10 @@ To start trusted node sync, run:
 
 === "Prater"
     ```sh
-    build/nimbus_beacon_node trustedNodeSync --network:prater \
-    --data-dir=build/data/shared_prater_0  \
-    --trusted-node-url=http://localhost:5052
+    build/nimbus_beacon_node trustedNodeSync \
+      --network:prater \
+      --data-dir=build/data/shared_prater_0 \
+      --trusted-node-url=http://localhost:5052
     ```
 
 If the command was executed successfully, following log lines will be visible: