Minor edits to the Docker documentation

docs/source/bigchaindb-cli.md

@@ -37,9 +37,9 @@ This command drops (erases) the RethinkDB database. You will be prompted to make
 This command starts BigchainDB. It always begins by trying a `bigchaindb init` first. See the note in the documentation for `bigchaindb init`.
 
 
-## bigchaindb load
+### bigchaindb load
 
-The command is used to run benchmarking tests. You can learn more about it using:
+This command is used to run benchmarking tests. You can learn more about it using:
 ```text
 $ bigchaindb load -h
 ```

docs/source/installing-server.md

@@ -113,104 +113,108 @@ If it's the first time you've run `bigchaindb start`, then it creates the databa
 
 For those who like using Docker and wish to experiment with BigchainDB in
 non-production environments, we currently maintain a Docker image and a
-`dockerfile` that can be used to build an image for `bigchaindb`.
+`Dockerfile` that can be used to build an image for `bigchaindb`.
 
-### Pull and run the image from Docker Hub
+### Pull and Run the Image from Docker Hub
 
-Assuming you have `docker` installed, you would proceed as follows.
+Assuming you have Docker installed, you would proceed as follows.
 
-In a terminal shell, pull the latest version of the BigchainDB Docker image
+In a terminal shell, pull the latest version of the BigchainDB Docker image using:
 ```text
 docker pull bigchaindb/bigchaindb:latest
 ```
 
 then do a one-time configuration step to create the config file; we will use
 the `-y` option to accept all the default values. The configuration file will
-be stored on your host machine under ` ~/bigchaindb_docker/.bigchaindb`:
+be stored in a file on your host machine at `~/bigchaindb_docker/.bigchaindb`:
 
 ```text
 $ docker run --rm -v "$HOME/bigchaindb_docker:/data" -ti \
-  bigchaindb/bigchaindb:latest configure
+  bigchaindb/bigchaindb:latest -y configure
 Generating keypair
 Configuration written to /data/.bigchaindb
 Ready to go!
 ```
 
-Let's analyze the command:
- - `docker run` tell docker to run some image
- - `--rm` remove the container once we are done
- - `-v "$HOME/bigchaindb_docker:/data` map the host directory
-   `$HOME/bigchaindb_docker` to the container directory `/data`,
-   this allow us to have the data persisted on the host machine,
-   you can read more in the [official Docker
-   documentation](https://docs.docker.com/engine/userguide/containers/dockervolumes/#mount-a-host-directory-as-a-data-volume)
- - `-t` allocate a pseudo-tty
- - `-i` keep STDIN open even if not attached
- - `bigchaindb/bigchaindb:latest` the image to use
- - `configure` the sub-command to execute
+Let's analyze that command:
+
+* `docker run` tells Docker to run some image
+* `--rm` remove the container once we are done
+* `-v "$HOME/bigchaindb_docker:/data"` map the host directory
+ `$HOME/bigchaindb_docker` to the container directory `/data`;
+ this allows us to have the data persisted on the host machine,
+ you can read more in the [official Docker
+ documentation](https://docs.docker.com/engine/userguide/containers/dockervolumes/#mount-a-host-directory-as-a-data-volume)
+* `-t` allocate a pseudo-TTY
+* `-i` keep STDIN open even if not attached
+* `bigchaindb/bigchaindb:latest` the image to use
+* `-y configure` execute the `configure` sub-command (of the `bigchaindb` command) inside the container, with the `-y` option to automatically use all the default config values
 
 
-After configuring the system, you can run BigchainDB with the following
-command:
+After configuring the system, you can run BigchainDB with the following command:
 
 ```text
 $ docker run -v "$HOME/bigchaindb_docker:/data" -d \
-  --name bigchaindb
+  --name bigchaindb \
   -p "58080:8080" -p "59984:9984" \
   bigchaindb/bigchaindb:latest start
 ```
 
 The command is slightly different from the previous one, the differences are:
- - `--name bigchaindb` give a nice name to the container, so it's easier to
-   refer to it later
- - `-p "58080:8080"` map the host port `58080` to the container port `8080`
-   (the RethinkDB admin interface)
- - `-p "59984:9984"` map the host port `59984` to the container port `9984`
-   (the BigchainDB API server)
- - `start` start the BigchainDB service
 
-Another way to publish the ports exposed by the containeris to use the `-P` (or
-`--publish-all`). This will publish all exposed ports to random ports. You can
+* `-d` run the container in the background
+* `--name bigchaindb` give a nice name to the container so it's easier to
+ refer to it later
+* `-p "58080:8080"` map the host port `58080` to the container port `8080`
+ (the RethinkDB admin interface)
+* `-p "59984:9984"` map the host port `59984` to the container port `9984`
+ (the BigchainDB API server)
+* `start` start the BigchainDB service
+
+Another way to publish the ports exposed by the container is to use the `-P` (or
+`--publish-all`) option. This will publish all exposed ports to random ports. You can
 always run `docker ps` to check the random mapping.
 
-You can also access the RethinkDB dashboard at:
+You can also access the RethinkDB dashboard at
 [http://localhost:58080/](http://localhost:58080/)
 
 If that doesn't work, then replace `localhost` with the IP or hostname of the
-machine running the Docker engine. If you are running docker-machine (e.g.: on
+machine running the Docker engine. If you are running docker-machine (e.g. on
 Mac OS X) this will be the IP of the Docker machine (`docker-machine ip
 machine_name`).
 
-#### Load test with Docker
+#### Load Testing with Docker
 
-After BigchainDB is running in the docker container named `bigchaindb`, we can
-start another container and run the load test against the first one.
+Now that we have BigchainDB running in the Docker container named `bigchaindb`, we can
+start another BigchainDB container to generate a load test for it.
 
-First, make sure the container `bigchaindb` is running, you can check this by running:
+First, make sure the container named `bigchaindb` is still running. You can check that using:
 ```text
 docker ps
 ```
 
-You should see a container named `bigchaindb` running.
+You should see a container named `bigchaindb` in the list.
+
+You can load test the BigchainDB running in that container by running the `bigchaindb load` command in a second container:
 
-Now, run a new container and link it to `bigchaindb` to run the load test.
 ```text
 $ docker run --rm -v "$HOME/bigchaindb_docker:/data" -ti \
   --link bigchaindb \
-  bigchaindb/bigchaindb:test load
+  bigchaindb/bigchaindb:latest load
 ```
 
-Note that load test transactions accepts also a `-m` option to enable
-multiprocessing and make use of all the cores in the host machine.
+Note the `--link` option to link to the first container (named `bigchaindb`).
 
-You can see BigchainDB processing your transactions running:
+Aside: The `bigchaindb load` command has several options (e.g. `-m`). You can read more about it in [the documentation about the BigchainDB command line interface](bigchaindb-cli.html).
+
+If you look at the RethinkDB dashboard (in your web browser), you should see the effects of the load test. You can also see some effects in the Docker logs using:
 ```text
 $ docker logs -f bigchaindb
 ```
 
-### Building your own image
+### Building Your Own Image
 
-Assuming you have `docker` installed, you would proceed as follows.
+Assuming you have Docker installed, you would proceed as follows.
 
 In a terminal shell:
 ```text
@@ -223,4 +227,3 @@ $ docker build --tag local-bigchaindb .
 ```
 
 Now you can use your own image to run BigchainDB containers.
-