Tidy docs

book/src/validator-manager-create.md

@@ -6,7 +6,7 @@ The `lighthouse validator-manager create` command derives validators from a
 mnemonic and produces two files:
 
 - `validators.json`: the keystores and passwords for the newly generated
-    validators in JSON format.
+    validators, in JSON format.
 - `deposits.json`: a JSON file of the same format as
     [staking-deposit-cli](https://github.com/ethereum/staking-deposit-cli) which can
     be used for deposit submission via the [Ethereum Staking
@@ -29,9 +29,9 @@ an internet-connected host.
 
 The `create` and `import` commands are recommended for advanced users who are
 familiar with command line tools and the practicalities of managing sensitive
-key information. **We recommend that novice users follow the workflow on
-[Ethereum Staking Launchpad][] rather than using the `move` and `create`
-tools.**
+cryptographic material. **We recommend that novice users follow the workflow on
+[Ethereum Staking Launchpad][] rather than using the `create` and `import`
+commands.**
 
 ## Simple Example
 
@@ -48,11 +48,11 @@ lighthouse \
     --output-path ./
 ```
 
-The `--suggested-fee-recipient` flag may be omitted to use whatever default
-value the VC uses. It does not necessarily need to be idential to
-`--eth1-withdrawal-address`.
+> The `--suggested-fee-recipient` flag may be omitted to use whatever default
+> value the VC uses. It does not necessarily need to be idential to
+> `--eth1-withdrawal-address`.
 
-Import the validators to a running VC with:
+Then, import the validators to a running VC with:
 
 ```bash
 lighthouse \
@@ -62,8 +62,8 @@ lighthouse \
     --vc-token <API-TOKEN-PATH>
 ```
 
-Be sure to remove `./validators.json` after the import is successful since it
-contains unencrypted validator keystores.
+> Be sure to remove `./validators.json` after the import is successful since it
+> contains unencrypted validator keystores.
 
 ## Detailed Guide
 
@@ -78,7 +78,7 @@ host. This would help protect the mnemonic from being exposed to the Internet.
 Run the `create` command, subsituting `<ADDRESS>` for an execution address that
 you control. This is where all the staked ETH and rewards will ultimately
 reside, so it's very important that this address is secure, acessible and
-backed-up.
+backed-up. The `create` command:
 
 ```bash
 lighthouse \
@@ -114,7 +114,7 @@ slashing!
 
 The command will create two files:
 
-- `./deposits.json`: this file does not contain sensitive information and may be uploaded to the [Ethereum Staking Launchpad].
+- `./deposits.json`: this file does *not* contain sensitive information and may be uploaded to the [Ethereum Staking Launchpad].
 - `./validators.json`: this file contains **sensitive unencrypted validator keys, do not share it with anyone or upload it to any website**.
 
 ### 2. Import the validators
@@ -172,4 +172,4 @@ shared with anyone.
 
 The validators will now go through 3-4 epochs of [doppelganger
 protection](./validator-doppelganger.md) and will automatically start performing
-their duties when they are deposited and activated.
+their duties when they are deposited and activated. The guide is complete.

book/src/validator-manager-move.md

@@ -10,35 +10,34 @@ operation is *comprehensive*; it will:
 - Enable the validators on the dest VC.
 - Generally result in very little or no validator downtime.
 
-It is capable of moving all validators on the src VC, a number of validators or
-specific validators from one VC to another.
+It is capable of moving all validators on the src VC, a count of validators or
+a list of pubkeys.
 
 The `move` command is only guaranteed to work between two Lighthouse VCs (i.e.,
-there is no guarantee that the commands will work between Lighthouse and Teku or
-another client).
+there is no guarantee that the commands will work between Lighthouse and Teku, for instance).
 
 The `move` command only supports moving validators using a keystore on the local
 file system, it does not support `Web3Signer` validators.
 
 Although all efforts are taken to avoid it, it's possible for the `move` command
-to fail in a way removes the validator from the src VC without adding it to the
+to fail in a way that removes the validator from the src VC without adding it to the
 dest VC. Therefore, it is recommended to **never use the `move` command without
-having a backup of all validator keystores (e.g., the mnemonic).**
+having a backup of all validator keystores (e.g. the mnemonic).**
 
 ## Simple Example
 
 The following command will move all validators from the VC running at
 `http://localhost:6062` to the VC running at `http://localhost:5062`.
 
-```
+```bash
 lighthouse \
 	validator-manager \
 	move \
 	--src-vc-url http://localhost:6062 \
 	--src-vc-token ~/src-token.txt \
 	--dest-vc-url http://localhost:5062 \
 	--dest-vc-token ~/.lighthouse/mainnet/validators/api-token.txt \
-	--validators all \
+	--validators all
 ```
 
 ## Detailed Guide
@@ -52,11 +51,18 @@ There will be two VCs in this example:
 - The *source* VC which contains the validators/keystores to be moved.
 - The *destination* VC which is to take the validators/keystores from the source.
 
-The example will assume the source VC is accessible at `src-host` and the destination VC is
-accessible at `dest-host`. Replace these values with your own hostnames or IP addresses.
+There will be two hosts in this example:
+
+- Host 1 (*"source host"*): Is running the `src-vc`.
+- Host 2 (*"destination host"*): Is running the `dest-vc`.
+
+The example will assume that all commands are run on Host 1. It also assumes
+that Host 1 is able to SSH to Host 2.
 
-The example assumes that the reader is currently logged into `dest-host` via SSH
-and that the reader can SSH from `dest-host` to `src-host`.
+In reality, many host configurations are possible. For example:
+
+- Both VCs on the same host.
+- Both VCs on different hosts and the `validator-manager` being used on a third host.
 
 ### 1. Configure the Source VC
 
@@ -102,25 +108,16 @@ lighthouse \
     --enable-doppelganger-protection
 ```
 
-The `--enable-doppelganger-protection` flag is not *strictly* required, however
-it is recommended for an additional layer of safety. It will result in 3-4
-epochs of downtime for the validator after it is moved, which is generally an
-inconsequential cost in lost rewards or penalties.
-
-Optionally, users can add the `--http-store-passwords-in-secrets-dir` flag if they'd like to have
-the import validator keystore passwords stored in separate files rather than in the
-`valdiator-definitions.yml` file. If you don't know what this means, you can safely omit the flag.
-
-### 3. Configure SSH
+> The `--enable-doppelganger-protection` flag is not *strictly* required, however
+> it is recommended for an additional layer of safety. It will result in 3-4
+> epochs of downtime for the validator after it is moved, which is generally an
+> inconsequential cost in lost rewards or penalties.
+> 
+> Optionally, users can add the `--http-store-passwords-in-secrets-dir` flag if they'd like to have
+> the import validator keystore passwords stored in separate files rather than in the
+> `valdiator-definitions.yml` file. If you don't know what this means, you can safely omit the flag.
 
-For this example to work, the `dest-host` host must be able to SSH to the `src-host` host. This
-configuration is out-of-scope of this article, however it probably involves adding a public key to
-the `.ssh/authorized_keys` file on the `dest-host` host.
-
-You will know this is complete when you can SSH to the `dest-host` from your PC and then run `ssh
-src-host` successfully.
-
-### 4. Obtain the Source API Token
+### 3. Obtain the Source API Token
 
 The VC API is protected by an *API token*. This is stored in a file on each of the hosts. Since
 we'll be running our command on the destination host, it will need to have the API token for the
@@ -151,19 +148,28 @@ this terminal window then the connection between the destination and source host
 With the SSH tunnel established between the `dest-host` and `src-host`, from the **destination
 host** run the command to move the validators:
 
-```
+```bash
 lighthouse \
 	validator-manager \
 	move \
 	--src-vc-url http://localhost:6062 \
 	--src-vc-token ~/src-token.txt \
 	--dest-vc-url http://localhost:5062 \
 	--dest-vc-token ~/.lighthouse/mainnet/validators/api-token.txt \
-	--validators all \
+	--validators all
 ```
 
 The command will provide information about the progress of the operation and
-emit `Done.` when the operation has completed successfully.
+emit `Done.` when the operation has completed successfully. For example:
+
+```bash
+Running validator manager for mainnet network
+Validator client is reachable at http://localhost:5062/ and reports 2 validators
+Validator client is reachable at http://localhost:6062/ and reports 0 validators
+Moved keystore 1 of 2
+Moved keystore 2 of 2
+Done.
+```
 
 Once the operation completes successfully, there is nothing else to be done. The
 validators have been removed from the `src-host` and enabled at the `dest-host`.

book/src/validator-manager.md

@@ -5,15 +5,15 @@
 
 ## Introduction
 
-The `lighthouse validator-manager` tool provides utilities for managing validators on a running
+The `lighthouse validator-manager` tool provides utilities for managing validators on a *running*
 Lighthouse Validator Client. The validator manager performs operations via the HTTP API of the
 validator client (VC). Due to limitations of the
 [keymanager-APIs](https://ethereum.github.io/keymanager-APIs/), only Lighthouse VCs are fully
 supported by this command.
 
-The validator manager tool is similar to the `lighthouse account-manager` tool, except the latter
-creates files that will be read by the VC next time it starts rather than making instant changes to
-a live VC.
+The validator manager tool is similar to the `lighthouse account-manager` tool,
+except the latter creates files that will be read by the VC next time it starts
+whilst the former makers instant changes to a live VC.
 
 The `account-manager` is ideal for importing keys created with the
 [staking-deposit-cli](https://github.com/ethereum/staking-deposit-cli). On the
@@ -26,10 +26,10 @@ The `validator-manager` boasts the following features:
 - One-line command to arbitrarily move validators between two VCs, maintaining the slashing protection database.
 - Generates deposit files compatible with the [Ethereum Staking Launchpad]().
 - Generally involves zero or very little downtime.
-- The "key cache" is preserved whenever a validator is added with the validator manager, this
-    prevents long waits at start up when a new validator is added.
+- The "key cache" is preserved whenever a validator is added with the validator
+    manager, preventing long waits at start up when a new validator is added.
 
-### Validator Manager Documentation
+## Guides
 
-- [Creating and importing validators using the `create` and `import` commands](./validator-manager-create.md)
-- [Moving validators between two VCs using the `move` command](./validator-manager.md)
+- [Creating and importing validators using the `create` and `import` commands.](./validator-manager-create.md)
+- [Moving validators between two VCs using the `move` command.](./validator-manager-move.md)