editted readme

README.md

@@ -1,39 +1,41 @@
 # Riak Test Docker Framework
-`riak-test-docker` is a test framework designed to manage docker-based Riak cluster for test environment.
+`riak-test-docker` is a test framework designed to manage a docker-based Riak cluster in a test environment.
 
 ## Table of contents
-* [`Preconditions`](#preconditions)
+* [`Prerequisites`](#prerequisites)
     * [`Additional environment configuration`](#additional-environment-configuration)
-* [`Using`](#using)
+* [`Using riak-test-docker`](#using-riak-test-docker)
     * [`Maven`](#maven)
     * [`Gradle`](#gradle)
     * [`SBT`](#sbt)
 * [`Quick Example`](#quick-example)
-* [`Creating and configuration cluster`](#creating-and-configuration-cluster)
+* [`Creating and configuring a cluster`](#creating-and-configuring-a-cluster)
     * [`System properties`](#system-properties)
 * [`Seamless JUnit integration`](#seamless-junit-integration)
     * [`@OverrideRiakClusterConfig annotation`](#overrideriakclusterconfig-annotation)
     * [`Disabling rule`](#disabling-rule)
 
-## Preconditions
+## Prerequisites
 For using `riak-test-docker` framework, [`Docker`](https://www.docker.com) must be installed and properly configured.
 
 #### Additional environment configuration
-Because of specific of using Docker on MacOS and Windows in current Docker implementation, before using `riak-test-docker` following environment variables **must** be configured:
+
+Due to the implementation of Docker on MacOS and Windows, the following environment variables **must** be configured before using `riak-test-docker` :
+
 * DOCKER_HOST="tcp://\<Docker Host IP\>:2376
 * DOCKER_CERT_PATH=\<path to Docker cert\>
 
-**Tip:** For MacOS following command must be used to configure Docker emvironment properly: `docker-machine env`. It will set all nessessary environment variables
+**Tip:** For MacOS, you must use `docker-machine env` to configure Docker emvironment properly. This command will set all nessessary environment variables.
 
-The second thing which is **must** be configured for MacOS and Windows operating systems is static route:
+The second thing which **must** be configured for MacOS and Windows is a static route:
  - for MacOS: `sudo route -n add 172.17.0.0/16 <Docker Host IP>`
  - for Windows: `route ADD 172.17.0.0 MASK 255.255.0.0 <Docker Host IP>`
 
-## Using
+## Using riak-test-docker
 
-Include the artifact into your project using Gradle, Maven or SBT.
+To use riak-test-docker, you muust include the `riak-test-docker` artifact into your project using Gradle, Maven or SBT.
 
-Make sure you've added the Basho Bintray repo by going here [https://bintray.com/basho/data-platform](https://bintray.com/basho/data-platform) and clicking the blue "SET ME UP!" button on the right of the page.
+Make sure you've added the Basho Bintray repo to your project by going here [https://bintray.com/basho/data-platform](https://bintray.com/basho/data-platform) and clicking the blue "SET ME UP!" button on the right-hand side of the page.
 
 
 ##### Maven
@@ -72,7 +74,9 @@ libraryDependencies ++= {
 ```
 
 ## Quick Example
-Before we go into details of how to configure and use ```riak-test-docker``` in your tests, let's take a quick look at simple example.
+
+Before we go into details of how to configure and use ```riak-test-docker``` in your tests, let's take a quick look at a simple example.
+
 ```java
   @Test
   public void testCluster() {
@@ -93,26 +97,29 @@ Before we go into details of how to configure and use ```riak-test-docker``` in
       }
   }
 ```
-This test method illustrates the simpliest use-case of `riak-test-docker` framework. Basically it consists only of 3 steps:
 
-1. Create new instance of DockerRiakCluster
-2. Start cluster
-3. Connect to started cluster using `com.basho.riak.test.cluster.DockerRiakCluster#getIps` method which provides an access to IP addresses of started Riak nodes.
-4. When cluster is not nessessary anymore it's ***required*** to stop it
+This test method illustrates the simplest use-case of the `riak-test-docker` framework. Basically, it consists only of 3 steps:
 
-## Creating and configuration cluster
-By default `DockerRiakCluster` instance is ready to use right after usual instance cteation, even without any additional configuration. But also there might be a need to edit default parameters. Following properties might be configured for dockerized Riak cluster:
+1. Create a new instance of DockerRiakCluster
+2. Start the Riak Docker cluster
+3. Connect to the started cluster using `com.basho.riak.test.cluster.DockerRiakCluster#getIps` method which provides access to the IP addresses of the started Riak nodes.
+4. When the cluster is no longer needed, you ***must*** stop it.
+
+## Creating and configuring a cluster
+
+By default, a `DockerRiakCluster` instance is ready to use right after the usual instance creation without any additional configuration required. However, there might also be a need to change the default parameters. The following properties can be configured for the dockerized Riak cluster:
 
 Property | Description | Default to
 ---------|-------------|-----------
-nodes | The total ammount of Riak cluster nodes | 1
-timeout | The maximum time to wait for cluster start | 1
+nodes | The total number of nodes in the Riak cluster | 1
+timeout | The maximum time to wait for the cluster to start | 1
 timeUnit | The time unit of the timeout property | TimeUnit.MINUTES
-imageName | The name of Docker image to use | basho/riak-ts:latest
+imageName | The name of the Docker image to use | basho/riak-ts:latest
 bucketTypes | The list of bucket types which should be created and activated after cluster start | n/d
-dockerClientBuilder | The Custom builder for Docker client | n/d
+dockerClientBuilder | The custom builder for the Docker client | n/d
+
+To make process of creation and configuration of `DockerRiakCluster` simple and flexible, a special builder was introduced: `com.basho.riak.test.cluster.DockerRiakCluster.Builder`. It contains methods which allow you to set all the properties listed earlier. An example of it's usage is shown below:
 
-To make process of creation and configuration of `DockerRiakCluster` more flexible and simple, special builder was introduced: `com.basho.riak.test.cluster.DockerRiakCluster.Builder`. It contains methods which allow to set all properties listed earlier. The example of it's usage is shown below:
 ```java
   DockerRiakCluster riakCluster = DockerRiakCluster.builder()
     .withNodes(2)
@@ -122,22 +129,24 @@ To make process of creation and configuration of `DockerRiakCluster` more flexib
     .build();
 ```
 
-**Note:** the usage of cluster builder is strongly recommended in most cases, because constructor-based approach could decreace code redability and quality.
+**Note:** Using the cluster builder is strongly recommended in most cases. The constructor-based approach can decrease code redability and quality.
 
 #### System properties
-Following system properties could be used to override cluster configuration globally:
+
+The following system properties may be used to override the global cluster configuration:
 
 Property | Description
 ---------|------------
 com.basho.riak.test.cluster.image-name | overrides configured Docker image name
 com.basho.riak.test.cluster.timeout | overrides start timeout (in minutes)
 
-If these properties are specified their analogs in builder configuration will be ignored.
+If these properties are specified, their analogs in builder configuration will be ignored.
 
 ## Seamless JUnit integration
+
 `riak-test-docker` provides a JUnit [`@Rule`](https://github.com/junit-team/junit4/wiki/Rules) implementation that manages an ad-hoc dockerized Riak cluster that makes testing applications that use Riak really easy.
 
-Create a test in the normal way. The only difference with using `riak-test-docker` is to add either a `@ClassRule` or a `@Rule` in your test on an instance of `com.basho.riak.test.rule.DockerRiakClusterRule`.
+To use the JUnit integration, you create a test in the normal way. The only difference with using `riak-test-docker` is to add either a `@ClassRule` or a `@Rule` in your test on an instance of `com.basho.riak.test.rule.DockerRiakClusterRule`.
 
 The following creates a static `@ClassRule` which will be invoked once at initialization of the test class and will then be cleaned up after all the tests are run. It will not destroy and re-create the cluster after each test (you'd use a normal `@Rule` for that).
 
@@ -150,9 +159,11 @@ The following creates a static `@ClassRule` which will be invoked once at initia
             .withTimeout(2));
 ```
 ### @OverrideRiakClusterConfig annotation
-Often test classes are built according to some class hierarchy. Usually this happens when developers don't want to duplicate a configuration code which is common for most of test classes and keep it in some base class. In such situation `DockerRiakClusterRule` could be also declared as a static field (`@ClassRule`) in that base class to avoid keeping it in each test class. Such approach is reasonable until all your tests require identical cluster configuration. But if, for example, there is a need to increase number of nodes for particular class without changing other common logic, it could be a real problem, because in this case you have to totally duplicate logic of base class inside current or increase a level of class hierarhy and create additional middle layer if base test classes.
 
-To solve such difficulties beforehand, the `@com.basho.riak.test.rule.annotations.OverrideRiakClusterConfig` annotation was introduced. It allows to override amount of nodes and starting timeout for particular class:
+Test classes are often built according to some class hierarchy. This usually happens when developers don't want to duplicate configuration code which is common for most of test classes. Common code is often kept in some base class. In such a situation, `DockerRiakClusterRule` could be declared as a static field (`@ClassRule`) in the base class to avoid keeping it in each test class. Such an approach is reasonable until all your tests require identical cluster configuration. But if, for example, there is a need to increase the number of nodes for particular class without changing other common logic, this could be a real problem. In this case, you have to totally duplicate the logic of base class inside the current class or go up a level in the class hierarhy and create additional middle layer for the base test classes.
+
+To solve such difficulties, the `@com.basho.riak.test.rule.annotations.OverrideRiakClusterConfig` annotation was introduced. It allows you to override the amount of nodes and starting timeout for particular class:
+
 ```java
   @OverrideRiakClusterConfig(nodes = 3, timeout = 3) // override class configuration
   public class DockerRiakClusterClassRuleTest {
@@ -170,7 +181,7 @@ To solve such difficulties beforehand, the `@com.basho.riak.test.rule.annotation
   }
 ```
 
-Described behavior also works for non-static `@Rule`. We can change amount of Riak nodes for particular test method by annotating it with `@OverrideRiakClusterConfig` annotation, even if test class contains non-static rule which will configure and start Riak cluster for each test method.
+The described behavior also works for a non-static `@Rule`. We can change the amount of Riak nodes for particular test method by annotating it with `@OverrideRiakClusterConfig` annotation. This works even if the test class contains a non-static rule which will configure and start a Riak cluster for each test method.
 ```java
 @Rule
 public DockerRiakClusterRule riakCluster = new DockerRiakClusterRule(
@@ -185,13 +196,16 @@ public void testClusterWithOverriddenNodesCount(){
 }
 ```
 
-### Disabling rule
-`DockerRiakClusterRule` can be totally disabled using special constructor parameter:
+### Disabling a rule
+
+`DockerRiakClusterRule` can be disabled using a special constructor parameter:
+
 ```java
 @ClassRule
 public static DockerRiakClusterRule riakCluster = new DockerRiakClusterRule(
         DockerRiakCluster.builder().withTimeout(3), true);
 ```
-If this addional parameter is set `true`, than docker cluster wont be started at all and `com.basho.riak.test.rule.DockerRiakClusterRule#getIps` will return empty set
 
-This feature might be helpful if there is a need to disable rule according to some condition (for example, disable if some system property configured)
+If this parameter is set `true`, the Docker cluster will not be started and `com.basho.riak.test.rule.DockerRiakClusterRule#getIps` will return an empty set.
+
+This feature might be helpful if there is a need to disable a rule according to some condition (for example, disable if some system property is configured).