Merge pull request #981 from filecoin-project/@jimmylee/docs-formatting

documentation: fixes formatting issue and removes copy issue

documentation/en/api-scripting-support.md

@@ -1,8 +1,6 @@
 # API Scripting Support
 
-You may want to delegate the work **Lotus Storage Miner** or **Lotus Node**
+You may want to delegate the work **Lotus Storage Miner** or **Lotus Node** perform to other machines. Here is how to setup the necessary authorization and environment variables.
-perform to other machines. Here is how to setup the necessary authorization and
-environment variables.
 
 ## Generate a JWT
 
@@ -15,12 +13,9 @@ lotus-storage-miner auth create-token --perm admin
 
 ## Environment variables
 
-Environmental variables are variables that are defined for the current shell and
+Environmental variables are variables that are defined for the current shell and are inherited by any child shells or processes. Environmental variables are used to pass information into processes that are spawned from the shell.
-are inherited by any child shells or processes. Environmental variables are used
-to pass information into processes that are spawned from the shell.
 
-Using the JWT you generated, you can assign it and the **multiaddr** to the
+Using the JWT you generated, you can assign it and the **multiaddr** to the appropriate environment variable.
-appropriate environment variable.
 
 ```sh
 # Lotus Node

documentation/en/api-troubleshooting.md

@@ -2,14 +2,11 @@
 
 ## Types: params
 
-`params` must be an array. If there are no `params` you should still pass an
+`params` must be an array. If there are no `params` you should still pass an empty array.
-empty array.
 
 ## Types: TipSet
 
-For methods such as `Filecoin.StateMinerPower`, where the method accepts the
+For methods such as `Filecoin.StateMinerPower`, where the method accepts the argument of the type `TipSet`, you can pass `null` to use the current chain head.
-argument of the type `TipSet`, you can pass `null` to use the current chain
-head.
 
 ```sh
 curl -X POST \
@@ -20,9 +17,7 @@ curl -X POST \
 
 ## Types: Sending a CID
 
-If you do not serialize the CID as a
+If you do not serialize the CID as a [JSON IPLD link](https://did-ipid.github.io/ipid-did-method/#txref), you will receive an error. Here is an example of a broken CURL request:
-[JSON IPLD link](https://did-ipid.github.io/ipid-did-method/#txref), you will
-receive an error. Here is an example of a broken CURL request:
 
 ```sh
 curl -X POST \

documentation/en/api.md

@@ -2,44 +2,37 @@
 
 Here is an early overview of how to make API calls.
 
-Implementation details for the **JSON-RPC** package are
+Implementation details for the **JSON-RPC** package are [here](https://github.com/filecoin-project/lotus/tree/master/lib/jsonrpc).
-[here](https://github.com/filecoin-project/lotus/tree/master/lib/jsonrpc).
 
 ## Overview: How do you modify the config.toml to change the API endpoint?
 
-API requests are made against `127.0.0.1:1234` unless you modify
+API requests are made against `127.0.0.1:1234` unless you modify `.lotus/config.toml`.
-`.lotus/config.toml`.
 
 Options:
 
 - `http://[api:port]/rpc/v0` - HTTP endpoint
 - `ws://[api:port]/rpc/v0` - Websocket endpoint
-- `PUT http://[api:port]/rest/v0/import` - File import, it requires write
+- `PUT http://[api:port]/rest/v0/import` - File import, it requires write permissions.
-  permissions.
 
 ## What methods can I use?
 
-For now, you can look into different files to find methods available to you
+For now, you can look into different files to find methods available to you based on your needs:
-based on your needs:
 
 - [Both Lotus node + storage miner APIs](https://github.com/filecoin-project/lotus/blob/master/api/api_common.go)
 - [Lotus node API](https://github.com/filecoin-project/lotus/blob/master/api/api_full.go)
 - [Storage miner API](https://github.com/filecoin-project/lotus/blob/master/api/api_storage.go)
 
-The necessary permissions for each are in
+The necessary permissions for each are in [api/struct.go](https://github.com/filecoin-project/lotus/blob/master/api/struct.go).
-[api/struct.go](https://github.com/filecoin-project/lotus/blob/master/api/struct.go).
 
 ## How do I make an API request?
 
-To demonstrate making an API request, we will take the method `ChainHead` from
+To demonstrate making an API request, we will take the method `ChainHead` from [api/api.go](https://github.com/filecoin-project/lotus/blob/master/api/api_full.go).
-[api/api.go](https://github.com/filecoin-project/lotus/blob/master/api/api_full.go).
 
 ```go
 ChainHead(context.Context) (*types.TipSet, error)
 ```
 
-And create a CURL command. In this command, `ChainHead` is included as
+And create a CURL command. In this command, `ChainHead` is included as `{ "method": "Filecoin.ChainHead" }`:
-`{ "method": "Filecoin.ChainHead" }`:
 
 ```sh
 curl -X POST \
@@ -58,20 +51,17 @@ curl -X POST \
      'http://127.0.0.1:1234/rpc/v0'
 ```
 
-> In the future we will add a playground to make it easier to build and
+> In the future we will add a playground to make it easier to build and experiment with API requests.
-> experiment with API requests.
 
 ## CURL authorization
 
-To authorize your request, you will need to include the **JWT** in a HTTP
+To authorize your request, you will need to include the **JWT** in a HTTP header, for example:
-header, for example:
 
 ```sh
 -H "Authorization: Bearer $(cat ~/.lotusstorage/token)"
 ```
 
-Admin token is stored in `~/.lotus/token` for the **Lotus Node** or
+Admin token is stored in `~/.lotus/token` for the **Lotus Node** or `~/.lotusstorage/token` for the **Lotus Storage Miner**.
-`~/.lotusstorage/token` for the **Lotus Storage Miner**.
 
 ## How do I generate a token?
 
@@ -87,12 +77,9 @@ lotus-storage-miner auth create-token --perm admin
 
 ## What authorization level should I use?
 
-When viewing
+When viewing [api/struct.go](https://github.com/filecoin-project/lotus/blob/master/api/struct.go), you will encounter these types:
-[api/struct.go](https://github.com/filecoin-project/lotus/blob/master/api/struct.go),
-you will encounter these types:
 
 - `read` - Read node state, no private data.
 - `write` - Write to local store / chain, and `read` permissions.
-- `sign` - Use private keys stored in wallet for signing, `read` and `write`
+- `sign` - Use private keys stored in wallet for signing, `read` and `write` permissions.
-  permissions.
 - `admin` - Manage permissions, `read`, `write`, and `sign` permissions.

documentation/en/dev-tools-jaeger-tracing.md

@@ -1,36 +1,24 @@
 # Jaeger Tracing
 
-Lotus has tracing built into many of its internals. To view the traces, first
+Lotus has tracing built into many of its internals. To view the traces, first download [Jaeger](https://www.jaegertracing.io/download/) (Choose the 'all-in-one' binary). Then run it somewhere, start up the lotus daemon, and open up localhost:16686 in your browser.
-download [Jaeger](https://www.jaegertracing.io/download/) (Choose the
-'all-in-one' binary). Then run it somewhere, start up the lotus daemon, and open
-up localhost:16686 in your browser.
 
 ## Open Census
 
-Lotus uses [OpenCensus](https://opencensus.io/) for tracing application flow.
+Lotus uses [OpenCensus](https://opencensus.io/) for tracing application flow. This generates spans through the execution of annotated code paths.
-This generates spans through the execution of annotated code paths.
 
-Currently it is set up to use Jaeger, though other tracing backends should be
+Currently it is set up to use Jaeger, though other tracing backends should be fairly easy to swap in.
-fairly easy to swap in.
 
 ## Running Locally
 
-To easily run and view tracing locally, first, install jaeger. The easiest way
+To easily run and view tracing locally, first, install jaeger. The easiest way to do this is to [download the binaries](https://www.jaegertracing.io/download/) and then run the `jaeger-all-in-one` binary. This will start up jaeger, listen for spans on `localhost:6831`, and expose a web UI for viewing traces on `http://localhost:16686/`.
-to do this is to [download the binaries](https://www.jaegertracing.io/download/)
-and then run the `jaeger-all-in-one` binary. This will start up jaeger, listen
-for spans on `localhost:6831`, and expose a web UI for viewing traces on
-`http://localhost:16686/`.
 
-Now, to start sending traces from Lotus to Jaeger, set the environment variable
+Now, to start sending traces from Lotus to Jaeger, set the environment variable `LOTUS_JAEGER` to `localhost:6831`, and start the `lotus daemon`.
-`LOTUS_JAEGER` to `localhost:6831`, and start the `lotus daemon`.
 
-Now, to view any generated traces, open up `http://localhost:16686/` in your
+Now, to view any generated traces, open up `http://localhost:16686/` in your browser.
-browser.
 
 ## Adding Spans
 
-To annotate a new codepath with spans, add the following lines to the top of the
+To annotate a new codepath with spans, add the following lines to the top of the function you wish to trace:
-function you wish to trace:
 
 ```go
 ctx, span := trace.StartSpan(ctx, "put function name here")

documentation/en/dev-tools-pond-ui.md

@@ -1,9 +1,6 @@
 # Pond UI
 
-Pond is a graphical testbed for [Lotus](https://docs.lotu.sh). Using it will
+Pond is a graphical testbed for [Lotus](https://docs.lotu.sh). Using it will setup a separate local network which is helpful for debugging. Pond will spin up nodes, connect them in a given topology, start them mining, and observe how they function over time.
-setup a separate local network which is helpful for debugging. Pond will spin up
-nodes, connect them in a given topology, start them mining, and observe how they
-function over time.
 
 ## Build
 
@@ -22,19 +19,14 @@ Now go to `http://127.0.0.1:2222`.
 ## What can I test?
 
 - The `Spawn Node` button starts a new **Lotus Node** in a new draggable window.
-- Click `[Spawn Storage Miner]` to start a **Lotus Storage Miner**. This
+- Click `[Spawn Storage Miner]` to start a **Lotus Storage Miner**. This require's the node's wallet to have funds.
-  require's the node's wallet to have funds.
+- Click on `[Client]` to open the **Lotus Node**'s client interface and propose a deal with an existing Miner. If successful you'll see a payment channel open up with that Miner.
-- Click on `[Client]` to open the **Lotus Node**'s client interface and propose
-  a deal with an existing Miner. If successful you'll see a payment channel open
-  up with that Miner.
 
-Don't leave Pond unattended for more than 10 hours, the web client will
+Don't leave Pond unattended for more than 10 hours, the web client will eventually consume all available RAM.
-eventually consume all available RAM.
 
 ## Troubleshooting
 
 - Turn it off and on - Start at the top
-- `rm -rf ~/.lotus ~/.lotusstorage/`, this command will delete chain sync data,
+- `rm -rf ~/.lotus ~/.lotusstorage/`, this command will delete chain sync data, stored wallets, and other configurations so be careful.
-  stored wallets, and other configurations so be careful.
 - Verify you have the correct versions of dependencies
 - If stuck on a bad fork, try `lotus chain sethead --genesis`

documentation/en/getting-started.md

@@ -1,36 +1,23 @@
 # Lotus
 
-Lotus is an implementation of the **Filecoin Distributed Storage Network**. You
+Lotus is an implementation of the **Filecoin Distributed Storage Network**. You can run the Lotus software client to join the **Filecoin Testnet**.
-can run the Lotus software client to join the **Filecoin Testnet** (when it
-launches).
 
-For more details about Filecoin, check out the
+For more details about Filecoin, check out the [Filecoin Spec](https://github.com/filecoin-project/specs).
-[Filecoin Spec](https://github.com/filecoin-project/specs).
 
 ## What can I learn here?
 
-- How to install Lotus on
+- How to install Lotus on [Arch Linux](https://docs.lotu.sh/en+install-lotus-arch), [Ubuntu](https://docs.lotu.sh/en+install-lotus-ubuntu), or [MacOS](https://docs.lotu.sh/en+install-lotus-macos).
-  [Arch Linux](https://docs.lotu.sh/en+install-lotus-arch),
-  [Ubuntu](https://docs.lotu.sh/en+install-lotus-ubuntu), or
-  [MacOS](https://docs.lotu.sh/en+install-lotus-macos).
 - Joining the [Lotus Testnet](https://docs.lotu.sh/en+join-testnet).
-- [Storing](https://docs.lotu.sh/en+storing-data) or
+- [Storing](https://docs.lotu.sh/en+storing-data) or [retrieving](https://docs.lotu.sh/en+retrieving-data) data.
-  [retrieving](https://docs.lotu.sh/en+retrieving-data) data.
+- Mining Filecoin using the **Lotus Storage Miner** in your [CLI](https://docs.lotu.sh/en+mining).
-- Mining Filecoin using the **Lotus Storage Miner** in your
-  [CLI](https://docs.lotu.sh/en+mining).
 
 ## What makes Lotus different?
 
-Lotus is architected modularly to keep clean API boundaries while using the same
+Lotus is architected modularly to keep clean API boundaries while using the same process. Installing Lotus will include two separate programs:
-process. Installing Lotus will include two separate programs:
 
 - The **Lotus Node**
 - The **Lotus Storage Miner**
 
-The **Lotus Storage Miner** is intended to be run on the machine that manages a
+The **Lotus Storage Miner** is intended to be run on the machine that manages a single storage miner instance, and is meant to communicate with the **Lotus Node** via the websocket **JSON-RPC** API for all of the chain interaction needs.
-single storage miner instance, and is meant to communicate with the **Lotus
-Node** via the websocket **JSON-RPC** API for all of the chain interaction
-needs.
 
-This way, a mining operation may easily run a **Lotus Storage Miner** or many of
+This way, a mining operation may easily run a **Lotus Storage Miner** or many of them, connected to one or many **Lotus Node** instances.
-them, connected to one or many **Lotus Node** instances.

documentation/en/hardware-mining.md

@@ -1,19 +1,10 @@
 # Protocol Labs Standard Testing Configuration
 
-> This documentation page describes the standard testing configuration the
+> This documentation page describes the standard testing configuration the Protocol Labs team has used to test **Lotus Storage Miner**s on Lotus. There is no guarantee this testing configuration will be suitable for Filecoin storage mining at MainNet launch. If you need to buy new hardware to join the Filecoin Testnet, we recommend to buy no more hardware than you require for testing. To learn more please read this [Protocol Labs Standard Testing Configuration post](https://filecoin.io/blog/filecoin-testnet-mining/).
-> Protocol Labs team has used to test **Lotus Storage Miner**s on Lotus. There
-> is no guarantee this testing configuration will be suitable for Filecoin
-> storage mining at MainNet launch. If you need to buy new hardware to join the
-> Filecoin Testnet, we recommend to buy no more hardware than you require for
-> testing. To learn more please read this
-> [Protocol Labs Standard Testing Configuration post](https://filecoin.io/blog/filecoin-testnet-mining/).
 
-**Sector sizes** and **minimum pledged storage** required to mine blocks are two
+**Sector sizes** and **minimum pledged storage** required to mine blocks are two very important Filecoin Testnet parameters that impact hardware decisions. We will continue to refine all parameters during Testnet.
-very important Filecoin Testnet parameters that impact hardware decisions. We
-will continue to refine all parameters during Testnet.
 
-BECAUSE OF THIS, OUR STANDARD TESTING CONFIGURATION FOR FILECOIN MAINNET CAN AND
+BECAUSE OF THIS, OUR STANDARD TESTING CONFIGURATION FOR FILECOIN MAINNET CAN AND WILL CHANGE. YOU HAVE BEEN WARNED.
-WILL CHANGE. YOU HAVE BEEN WARNED.
 
 ## Example configuration
 
@@ -23,19 +14,15 @@ The setup below is a minimal example for sealing 32 GiB sectors on Lotus:
 - 8 core CPU
 - 128 GiB of RAM
 
-Note that 1GB sectors don't require as high of specs, but are likely to be
+Note that 1GB sectors don't require as high of specs, but are likely to be removed as we improve the performance of 32GB sector sealing.
-removed as we improve the performance of 32GB sector sealing.
 
 ## Testnet discoveries
 
-- If you only have 128GiB of ram, enabling 256GB of **NVMe** swap on an SSD will
+- If you only have 128GiB of ram, enabling 256GB of **NVMe** swap on an SSD will help you avoid out-of-memory issues while mining.
-  help you avoid out-of-memory issues while mining.
 
 ## Benchmarked GPUs
 
-GPUs are a must for getting **block rewards**. Here are a few that have been
+GPUs are a must for getting **block rewards**. Here are a few that have been confirmed to generate **SNARKs** quickly enough to successfully mine blocks on the Lotus Testnet.
-confirmed to generate **SNARKs** quickly enough to successfully mine blocks on
-the Lotus Testnet.
 
 - GeForce RTX 2080 Ti
 - GeForce RTX 2080 SUPER
@@ -46,8 +33,7 @@ the Lotus Testnet.
 
 ## Testing other GPUs
 
-If you want to test a GPU that is not explicitly supported, you can use the
+If you want to test a GPU that is not explicitly supported, you can use the following configuration flag:
-following configuration flag:
 
 ```sh
 BELLMAN_CUSTOM_GPU="<NAME>:<NUMBER_OF_CORES>"
@@ -59,14 +45,8 @@ Here is an example of trying a GeForce GTX 1660 ti with 1536 cores.
 BELLMAN_CUSTOM_GPU="GeForce GTX 1660 Ti:1536"
 ```
 
-To get the number of cores for your GPU, you will need to check your card’s
+To get the number of cores for your GPU, you will need to check your card’s specifications.
-specifications.
 
 ## Benchmarking
 
-Here is a
+Here is a [benchmarking tool](https://github.com/filecoin-project/lotus/tree/testnet-staging/cmd/lotus-bench) and a [GitHub issue thread](https://github.com/filecoin-project/lotus/issues/694) for those who wish to experiment with and contribute hardware setups for the **Filecoin Testnet**.
-[benchmarking tool](https://github.com/filecoin-project/lotus/tree/testnet-staging/cmd/lotus-bench)
-and a
-[GitHub issue thread](https://github.com/filecoin-project/lotus/issues/694) for
-those who wish to experiment with and contribute hardware setups for the
-**Filecoin Testnet**.

documentation/en/hardware.md

@@ -1,9 +1,7 @@
 # Hardware
 
-> This page is a work in progress. Exact mining requirements are still in the
+> This page is a work in progress. Exact mining requirements are still in the works.
-> works.
 
-Lotus can build and run on most [Linux](https://ubuntu.com/) and
+Lotus can build and run on most [Linux](https://ubuntu.com/) and [MacOS](https://www.apple.com/macos) systems with at least 8GiB of RAM.
-[MacOS](https://www.apple.com/macos) systems with at least 8GiB of RAM.
 
 Windows is not yet supported.

documentation/en/install-lotus-arch.md

@@ -41,6 +41,4 @@ make clean && make all
 sudo make install
 ```
 
-After installing Lotus, you can run the `lotus` command directly from your CLI
+After installing Lotus, you can run the `lotus` command directly from your CLI to see usage documentation. Next, you can join the [Lotus Testnet](https://docs.lotu.sh/en+join-testnet).
-to see usage documentation. Next, you can join the
-[Lotus Testnet](https://docs.lotu.sh/en+join-testnet).

documentation/en/install-lotus-macos.md

@@ -2,15 +2,13 @@
 
 ## Get XCode Command Line Tools
 
-To check if you already have the XCode Command Line Tools installed via the CLI,
+To check if you already have the XCode Command Line Tools installed via the CLI, run:
-run:
 
 ```sh
 xcode-select -p
 ```
 
-If this command returns a path, you can move on to the next step. Otherwise, to
+If this command returns a path, you can move on to the next step. Otherwise, to install via the CLI, run:
-install via the CLI, run:
 
 ```sh
 xcode-select --install
@@ -25,8 +23,7 @@ xcode-select --install
 
 ## Get HomeBrew
 
-We recommend that MacOS users use [HomeBrew](https://brew.sh) to install each
+We recommend that MacOS users use [HomeBrew](https://brew.sh) to install each the necessary packages.
-the necessary packages.
 
 Check if you have HomeBrew:
 
@@ -34,8 +31,7 @@ Check if you have HomeBrew:
 brew -v
 ```
 
-This command returns a version number if you have HomeBrew installed and nothing
+This command returns a version number if you have HomeBrew installed and nothing otherwise.
-otherwise.
 
 In your terminal, enter this command to install Homebrew:
 
@@ -63,6 +59,4 @@ make clean && make all
 sudo make install
 ```
 
-After installing Lotus, you can run the `lotus` command directly from your CLI
+After installing Lotus, you can run the `lotus` command directly from your CLI to see usage documentation. Next, you can join the [Lotus Testnet](https://docs.lotu.sh/en+join-testnet).
-to see usage documentation. Next, you can join the
-[Lotus Testnet](https://docs.lotu.sh/en+join-testnet).

documentation/en/install-lotus-ubuntu.md

@@ -44,6 +44,4 @@ make clean && make all
 sudo make install
 ```
 
-After installing Lotus, you can run the `lotus` command directly from your CLI
+After installing Lotus, you can run the `lotus` command directly from your CLI to see usage documentation. Next, you can join the [Lotus Testnet](https://docs.lotu.sh/en+join-testnet).
-to see usage documentation. Next, you can join the
-[Lotus Testnet](https://docs.lotu.sh/en+join-testnet).

documentation/en/join-testnet.md

@@ -2,12 +2,9 @@
 
 ## Introduction
 
-Anyone can set up a **Lotus Node** and connect to the **Lotus Testnet**. This is
+Anyone can set up a **Lotus Node** and connect to the **Lotus Testnet**. This is the best way to explore the current CLI and the **Filecoin Decentralized Storage Market**.
-the best way to explore the current CLI and the **Filecoin Decentralized Storage
-Market**.
 
-If you have installed older versions, you may need to clear existing chain data,
+If you have installed older versions, you may need to clear existing chain data, stored wallets and miners if you run into any errors. You can use this command:
-stored wallets and miners if you run into any errors. You can use this command:
 
 ```sh
 rm -rf ~/.lotus ~/.lotusstorage
@@ -27,15 +24,11 @@ In another terminal window, check your connection with peers:
 lotus net peers | wc -l
 ```
 
-In order to connect to the network, you need to be connected to at least 1 peer.
+In order to connect to the network, you need to be connected to at least 1 peer. If you’re seeing 0 peers, read our [troubleshooting notes](https://docs.lotu.sh/en+setup-troubleshooting).
-If you’re seeing 0 peers, read our
-[troubleshooting notes](https://docs.lotu.sh/en+setup-troubleshooting).
 
 ## Chain sync
 
-While the daemon is running, the next requirement is to sync the chain. Run the
+While the daemon is running, the next requirement is to sync the chain. Run the command below to start the chain sync progress. To see current chain height, visit the [network stats page](http://stats.testnet.filecoin.io/).
-command below to start the chain sync progress. To see current chain height,
-visit the [network stats page](http://stats.testnet.filecoin.io/).
 
 ```sh
 lotus sync wait
@@ -58,22 +51,19 @@ Here is an example of the response:
 t3vhfme4qfvegqaz7m7q6o6afjcs67n6kpzv7t2eozio4chwpafwa2y4l7zhwd5eom7jmihzdg4s52dpvnclza
 ```
 
-- Visit the [faucet](https://lotus-faucet.kittyhawk.wtf/funds.html) to add
+- Visit the [faucet](https://lotus-faucet.kittyhawk.wtf/funds.html) to add funds.
-  funds.
 - Paste the address you created.
 - Press the send button.
 
 ## Check wallet address balance
 
-Wallet balances in the Lotus Testnet are in **FIL**, the smallest denomination
+Wallet balances in the Lotus Testnet are in **FIL**, the smallest denomination of FIL is an **attoFil**, where 1 attoFil = 10^-18 FIL.
-of FIL is an **attoFil**, where 1 attoFil = 10^-18 FIL.
 
 ```sh
 lotus wallet balance <YOUR_NEW_ADDRESS>
 ```
 
-You will not see any attoFIL in your wallet if your **chain** is not fully
+You will not see any attoFIL in your wallet if your **chain** is not fully synced.
-synced.
 
 ## Send FIL to another wallet
 
@@ -85,7 +75,4 @@ lotus send <target> <amount>
 
 ## Monitor the dashboard
 
-To see the latest network activity, including **chain block height**, **block
+To see the latest network activity, including **chain block height**, **block height**, **blocktime**, **total network power**, largest **block producer miner**, check out the [monitoring dashboard](https://stats.testnet.filecoin.io).
-height**, **blocktime**, **total network power**, largest **block producer
-miner**, check out the
-[monitoring dashboard](https://stats.testnet.filecoin.io).

documentation/en/local-dev-net.md

@@ -1,7 +1,6 @@
 # Setup Local Devnet
 
-Build the Lotus Binaries in debug mode, This enables the use of 1024 byte
+Build the Lotus Binaries in debug mode, This enables the use of 1024 byte sectors.
-sectors.
 
 ```sh
 make debug

documentation/en/mining-lotus-seal-worker.md

@@ -1,9 +1,6 @@
 # Lotus Seal Worker
 
-The **Lotus Seal Worker** is an extra process that can offload heavy processing
+The **Lotus Seal Worker** is an extra process that can offload heavy processing tasks from your **Lotus Storage Miner**. It can be run on the same machine as your `lotus-storage-miner`, or on another machine communicating over a fast network.
-tasks from your **Lotus Storage Miner**. It can be run on the same machine as
-your `lotus-storage-miner`, or on another machine communicating over a fast
-network.
 
 ## Get Started
 
@@ -15,18 +12,11 @@ make lotus-seal-worker
 
 ## Running Alongside Storage Miner
 
-You may wish to run the **Lotus Seal Worker** on the same computer as the
+You may wish to run the **Lotus Seal Worker** on the same computer as the **Lotus Storage Miner**. This allows you to easily set the process priority of the sealing tasks to be lower than the priority of your more important storage miner process.
-**Lotus Storage Miner**. This allows you to easily set the process priority of
-the sealing tasks to be lower than the priority of your more important storage
-miner process.
 
-To do this, simply run `lotus-seal-worker run`, and the seal worker will
+To do this, simply run `lotus-seal-worker run`, and the seal worker will automatically pick up the correct authentication tokens from the `LOTUS_STORAGE_PATH` miner repository.
-automatically pick up the correct authentication tokens from the
-`LOTUS_STORAGE_PATH` miner repository.
 
-To check that the **Lotus Seal Worker** is properly connected to your storage
+To check that the **Lotus Seal Worker** is properly connected to your storage miner, run `lotus-storage-miner info` and check that the remote worker count has increased.
-miner, run `lotus-storage-miner info` and check that the remote worker count has
-increased.
 
 ```sh
 why@computer ~/lotus> lotus-storage-miner info
@@ -44,15 +34,11 @@ Sectors:  map[Committing:0 Proving:0 Total:0]
 
 Warning: This setup is a little more complex than running it locally.
 
-To use an entirely separate computer for sealing tasks, you will want to run the
+To use an entirely separate computer for sealing tasks, you will want to run the `lotus-seal-worker` on a separate machine, connected to your **Lotus Storage Miner** via the local area network.
-`lotus-seal-worker` on a separate machine, connected to your **Lotus Storage
-Miner** via the local area network.
 
-First, you will need to ensure your `lotus-storage-miner`'s API is accessible
+First, you will need to ensure your `lotus-storage-miner`'s API is accessible over the network.
-over the network.
 
-To do this, open up `~/.lotusstorage/config.toml` (Or if you manually set
+To do this, open up `~/.lotusstorage/config.toml` (Or if you manually set `LOTUS_STORAGE_PATH`, look under that directory) and look for the API field.
-`LOTUS_STORAGE_PATH`, look under that directory) and look for the API field.
 
 Default config:
 
@@ -61,25 +47,15 @@ Default config:
 ListenAddress = "/ip4/127.0.0.1/tcp/2345/http"
 ```
 
-To make your node accessible over the local area network, you will need to
+To make your node accessible over the local area network, you will need to determine your machines IP on the LAN, and change the `127.0.0.1` in the file to that address.
-determine your machines IP on the LAN, and change the `127.0.0.1` in the file to
-that address.
 
-A more permissive and less secure option is to change it to `0.0.0.0`. This will
+A more permissive and less secure option is to change it to `0.0.0.0`. This will allow anyone who can connect to your computer on that port to access the [API](https://docs.lotu.sh/en+api). They will still need an auth token.
-allow anyone who can connect to your computer on that port to access the
-[API](https://docs.lotu.sh/en+api). They will still need an auth token.
 
-Next, you will need to
+Next, you will need to [create an authentication token](https://docs.lotu.sh/en+api-scripting-support#generate-a-jwt-46). All Lotus APIs require authentication tokens to ensure your processes are as secure against attackers attempting to make unauthenticated requests to them.
-[create an authentication token](https://docs.lotu.sh/en+api-scripting-support#generate-a-jwt-46).
-All Lotus APIs require authentication tokens to ensure your processes are as
-secure against attackers attempting to make unauthenticated requests to them.
 
 ### Connect the Lotus Seal Worker
 
-On the machine that will run `lotus-seal-worker`, set the `STORAGE_API_INFO`
+On the machine that will run `lotus-seal-worker`, set the `STORAGE_API_INFO` environment variable to `TOKEN:STORAGE_NODE_MULTIADDR`. Where `TOKEN` is the token we created above, and `STORAGE_NODE_MULTIADDR` is the `multiaddr` of the **Lotus Storage Miner** API that was set in `config.toml`.
-environment variable to `TOKEN:STORAGE_NODE_MULTIADDR`. Where `TOKEN` is the
-token we created above, and `STORAGE_NODE_MULTIADDR` is the `multiaddr` of the
-**Lotus Storage Miner** API that was set in `config.toml`.
 
 Once this is set, run:
 
@@ -87,9 +63,7 @@ Once this is set, run:
 lotus-seal-worker run
 ```
 
-To check that the **Lotus Seal Worker** is connected to your **Lotus Storage
+To check that the **Lotus Seal Worker** is connected to your **Lotus Storage Miner**, run `lotus-storage-miner info` and check that the remote worker count has increased.
-Miner**, run `lotus-storage-miner info` and check that the remote worker count
-has increased.
 
 ```sh
 why@computer ~/lotus> lotus-storage-miner info

documentation/en/mining-troubleshooting.md

@@ -2,8 +2,7 @@
 
 ## Config: Filecoin Proof Parameters directory
 
-If you want to put the **Filecoin Proof Parameters** in a different directory,
+If you want to put the **Filecoin Proof Parameters** in a different directory, use the following environment variable:
-use the following environment variable:
 
 ```sh
 FIL_PROOFS_PARAMETER_CACHE
@@ -11,15 +10,13 @@ FIL_PROOFS_PARAMETER_CACHE
 
 ## Error: Can't acquire bellman.lock
 
-The **Bellman** lockfile is created to lock a GPU for a process. This bug can
+The **Bellman** lockfile is created to lock a GPU for a process. This bug can occur when this file isn't properly cleaned up:
-occur when this file isn't properly cleaned up:
 
 ```sh
 mining block failed: computing election proof: github.com/filecoin-project/lotus/miner.(*Miner).mineOne
 ```
 
-This bug occurs when the storage miner can't acquire the `bellman.lock`. To fix
+This bug occurs when the storage miner can't acquire the `bellman.lock`. To fix it you need to stop the `lotus-storage-miner` and remove `/tmp/bellman.lock`.
-it you need to stop the `lotus-storage-miner` and remove `/tmp/bellman.lock`.
 
 ## Error: Failed to get api endpoint
 
@@ -28,8 +25,7 @@ lotus-storage-miner info
 # WARN  main  lotus-storage-miner/main.go:73  failed to get api endpoint: (/Users/myrmidon/.lotusstorage) %!w(*errors.errorString=&{API not running (no endpoint)}):
 ```
 
-If you see this, that means your **Lotus Storage Miner** isn't ready yet. You
+If you see this, that means your **Lotus Storage Miner** isn't ready yet. You need to finish [syncing the chain](https://docs.lotu.sh/en+join-testnet).
-need to finish [syncing the chain](https://docs.lotu.sh/en+join-testnet).
 
 ## Error: Your computer may not be fast enough
 
@@ -37,8 +33,7 @@ need to finish [syncing the chain](https://docs.lotu.sh/en+join-testnet).
 CAUTION: block production took longer than the block delay. Your computer may not be fast enough to keep up
 ```
 
-If you see this, that means your computer is too slow and your blocks are not
+If you see this, that means your computer is too slow and your blocks are not included in the chain, and you will not receive any rewards.
-included in the chain, and you will not receive any rewards.
 
 ## Error: No space left on device
 
@@ -47,26 +42,16 @@ lotus-storage-miner pledge-sector
 # No space left on device (os error 28)
 ```
 
-If you see this, that means `pledge-sector` wrote too much data to `$TMPDIR`
+If you see this, that means `pledge-sector` wrote too much data to `$TMPDIR` which by default is the root partition (This is common for Linux setups). Usually your root partition does not get the largest partition of storage so you will need to change the environment variable to something else.
-which by default is the root partition (This is common for Linux setups).
-Usually your root partition does not get the largest partition of storage so you
-will need to change the environment variable to something else.
 
 ## Error: GPU unused
 
-If you suspect that your GPU is not being used, first make sure it is properly
+If you suspect that your GPU is not being used, first make sure it is properly configured as described in the [testing configuration page](hardware-mining.md). Once you've done that (and set the `BELLMAN_CUSTOM_GPU` as appropriate if necessary) you can verify your GPU is being used by running a quick lotus-bench benchmark.
-configured as described in the [testing configuration page](hardware-mining.md).
-Once you've done that (and set the `BELLMAN_CUSTOM_GPU` as appropriate if
-necessary) you can verify your GPU is being used by running a quick lotus-bench
-benchmark.
 
-First, to watch GPU utilization run `nvtop` in one terminal, then in a separate
+First, to watch GPU utilization run `nvtop` in one terminal, then in a separate terminal, run:
-terminal, run:
 
 ```sh
 lotus-bench --sector-size=1024
 ```
 
-This process uses a fair amount of GPU, and generally takes ~4 minutes to
+This process uses a fair amount of GPU, and generally takes ~4 minutes to complete. If you do not see any activity in nvtop from lotus during the entire process, it is likely something is misconfigured with your GPU.
-complete. If you do not see any activity in nvtop from lotus during the entire
-process, it is likely something is misconfigured with your GPU.

documentation/en/mining.md

@@ -1,17 +1,14 @@
 # Storage Mining
 
-Here are instructions to learn how to perform storage mining. For hardware
+Here are instructions to learn how to perform storage mining. For hardware specifications please read [this](https://docs.lotu.sh/en+hardware-mining).
-specifications please read [this](https://docs.lotu.sh/en+hardware-mining).
 
-It is useful to [join the Testnet](https://docs.lotu.sh/en+join-testnet) prior
+It is useful to [join the Testnet](https://docs.lotu.sh/en+join-testnet) prior to attempting storage mining for the first time.
-to attempting storage mining for the first time.
 
 NOTE: While a miner is running, there will be many `WARN` and `ERROR` logs.
 
 ## Get started
 
-Please ensure that at least one **BLS address** in your wallet exists with the
+Please ensure that at least one **BLS address** in your wallet exists with the following command:
-following command:
 
 ```sh
 lotus wallet list
@@ -53,8 +50,7 @@ To mine:
 lotus-storage-miner run
 ```
 
-If you are downloading **Filecoin Proof Parameters**, the download can take some
+If you are downloading **Filecoin Proof Parameters**, the download can take some time.
-time.
 
 Get information about your miner:
 
@@ -69,9 +65,7 @@ lotus-storage-miner info
 lotus-storage-miner pledge-sector
 ```
 
-- Warning: On Linux configurations, this command will write data to `$TMPDIR`
+- Warning: On Linux configurations, this command will write data to `$TMPDIR` which is not usually the largest partition. You should point the value to a larger partition if possible.
-  which is not usually the largest partition. You should point the value to a
-  larger partition if possible.
 
 Get **miner power** and **sector usage**:
 

documentation/en/retrieving-data.md

@@ -1,15 +1,10 @@
 # Retrieving Data
 
-> There are recent bug reports with these instructions. If you happen to
+> There are recent bug reports with these instructions. If you happen to encounter any problems, please create a [GitHub issue](https://github.com/filecoin-project/lotus/issues/new) and a maintainer will address the problem as soon as they can.
-> encounter any problems, please create a
-> [GitHub issue](https://github.com/filecoin-project/lotus/issues/new) and a
-> maintainer will address the problem as soon as they can.
 
-Here are the operations you can perform after you have stored and sealed a
+Here are the operations you can perform after you have stored and sealed a **Data CID** with the **Lotus Storage Miner** in the network.
-**Data CID** with the **Lotus Storage Miner** in the network.
 
-If you would like to learn how to store a **Data CID** on a miner, read the
+If you would like to learn how to store a **Data CID** on a miner, read the instructions [here](https://docs.lotu.sh/en+storing-data).
-instructions [here](https://docs.lotu.sh/en+storing-data).
 
 ## Find by Data CID
 
@@ -27,8 +22,6 @@ All fields are required.
 lotus client retrieve <Data CID> <outfile>
 ```
 
-If the outfile does not exist it will be created in the Lotus repository
+If the outfile does not exist it will be created in the Lotus repository directory.
-directory.
 
-This command will initiate a **retrieval deal** and write the data to your
+This command will initiate a **retrieval deal** and write the data to your computer. This process may take 2 to 10 minutes.
-computer. This process may take 2 to 10 minutes.

documentation/en/setting-a-static-port.md

@@ -1,14 +1,10 @@
 # Static Ports
 
-Depending on how your network is set up, you may need to set a static port to
+Depending on how your network is set up, you may need to set a static port to successfully connect to peers to perform storage deals with your **Lotus Storage Miner**.
-successfully connect to peers to perform storage deals with your **Lotus Storage
-Miner**.
 
 ## Setup
 
-To change the random **swarm port**, you may edit the `config.toml` file located
+To change the random **swarm port**, you may edit the `config.toml` file located under `$LOTUS_STORAGE_PATH`. The default location of this file is `$HOME/.lotusstorage`.
-under `$LOTUS_STORAGE_PATH`. The default location of this file is
-`$HOME/.lotusstorage`.
 
 To change the port to `1347`:
 
@@ -27,8 +23,7 @@ Open firewall manually:
 ufw allow 1347/tcp
 ```
 
-Or open and modify the profile located at
+Or open and modify the profile located at `/etc/ufw/applications.d/lotus-daemon`:
-`/etc/ufw/applications.d/lotus-daemon`:
 
 ```sh
 [Lotus Daemon]

documentation/en/setup-troubleshooting.md

@@ -2,16 +2,13 @@
 
 ## Config: Clearing data
 
-Here is a command that will delete your chain data, stored wallets, stored data
+Here is a command that will delete your chain data, stored wallets, stored data and any miners you have set up:
-and any miners you have set up:
 
 ```sh
 rm -rf ~/.lotus ~/.lotusstorage
 ```
 
-This command usually resolves any issues with running `lotus` but it is not
+This command usually resolves any issues with running `lotus` but it is not always required for updates. We will share information about when resetting your chain data and miners is required for an update in the future.
-always required for updates. We will share information about when resetting your
-chain data and miners is required for an update in the future.
 
 ## Error: Failed to connect bootstrap peer
 
@@ -20,15 +17,13 @@ WARN  peermgr peermgr/peermgr.go:131  failed to connect to bootstrap peer: faile
   * [/ip4/147.75.80.17/tcp/1347] failed to negotiate security protocol: connected to wrong peer
 ```
 
-- Try running the build steps again and make sure that you have the latest code
+- Try running the build steps again and make sure that you have the latest code from GitHub.
-  from GitHub.
 
 ```sh
 ERROR hello hello/hello.go:81 other peer has different genesis!
 ```
 
-- Try deleting your file system's `~/.lotus` directory. Check that it exists
+- Try deleting your file system's `~/.lotus` directory. Check that it exists with `ls ~/.lotus`.
-  with `ls ~/.lotus`.
 
 ```sh
 - repo is already locked

documentation/en/storing-data-troubleshooting.md

@@ -18,13 +18,10 @@ WARN  main  lotus/main.go:72  failed to start deal: computing commP failed: gene
 
 ## Error: 0kb file response during retrieval
 
-In order to retrieve a file, it must be sealed. Miners can check sealing
+In order to retrieve a file, it must be sealed. Miners can check sealing progress with this command:
-progress with this command:
 
 ```sh
 lotus-storage-miner sectors list
 ```
 
-When sealing is complete, `pSet: NO` will become `pSet: YES`. From now on the
+When sealing is complete, `pSet: NO` will become `pSet: YES`. From now on the **Data CID** is [retrievable](https://docs.lotu.sh/en+retrieving-data) from the **Lotus Storage Miner**.
-**Data CID** is [retrievable](https://docs.lotu.sh/en+retrieving-data) from the
-**Lotus Storage Miner**.

documentation/en/storing-data.md

@@ -1,9 +1,6 @@
 # Storing Data
 
-> There are recent bug reports with these instructions. If you happen to
+> There are recent bug reports with these instructions. If you happen to encounter any problems, please create a [GitHub issue](https://github.com/filecoin-project/lotus/issues/new) and a maintainer will address the problem as soon as they can.
-> encounter any problems, please create a
-> [GitHub issue](https://github.com/filecoin-project/lotus/issues/new) and a
-> maintainer will address the problem as soon as they can.
 
 Here are instructions for how to store data on the **Lotus Testnet**.
 
@@ -19,8 +16,7 @@ Upon success, this command will return a **Data CID**.
 
 ## List your local files
 
-The command to see a list of files by `CID`, `name`, `size` in bytes, and
+The command to see a list of files by `CID`, `name`, `size` in bytes, and `status`:
-`status`:
 
 ```sh
 lotus client local
@@ -54,11 +50,8 @@ lotus client deal <Data CID> <miner> <price> <duration>
 ```
 
 - Price is in attoFIL.
-- The `duration`, which represents how long the miner will keep your file
+- The `duration`, which represents how long the miner will keep your file hosted, is represented in blocks. Each block represents 45 seconds.
-  hosted, is represented in blocks. Each block represents 45 seconds.
 
 Upon success, this command will return a **Deal CID**.
 
-The storage miner will need to **seal** the file before it can be retrieved. If
+The storage miner will need to **seal** the file before it can be retrieved. If the **Lotus Storage Miner** is not running on a machine designed for sealing, the process will take a very long time.
-the **Lotus Storage Miner** is not running on a machine designed for sealing,
-the process will take a very long time.

documentation/en/updating-lotus.md

@@ -1,7 +1,6 @@
 # Updating Lotus
 
-If you installed Lotus on your machine, you can upgrade to the latest version by
+If you installed Lotus on your machine, you can upgrade to the latest version by doing the following:
-doing the following:
 
 ```sh
 # get the latest
@@ -11,16 +10,12 @@ git pull origin master
 make clean && make build
 ```
 
-Sometimes when you run Lotus after a pull, certain commands such as
+Sometimes when you run Lotus after a pull, certain commands such as `lotus daemon` may break.
-`lotus daemon` may break.
 
-Here is a command that will delete your chain data, stored wallets and any
+Here is a command that will delete your chain data, stored wallets and any miners you have set up:
-miners you have set up:
 
 ```sh
 rm -rf ~/.lotus ~/.lotusstorage
 ```
 
-This command usually resolves any issues with running `lotus` commands but it is
+This command usually resolves any issues with running `lotus` commands but it is not always required for updates. We will share information about when resetting your chain data and miners is required for an update in the future.
-not always required for updates. We will share information about when resetting
-your chain data and miners is required for an update in the future.