elastic · danielmitterdorfer · May 11, 2018 · Apr 28, 2018 · May 11, 2018
diff --git a/docs/adding_tracks.rst b/docs/adding_tracks.rst
@@ -4,10 +4,7 @@ Define Custom Workloads: Tracks
 Definition
 ----------
 
-A track is the specification of one or more benchmarking scenarios with a specific document corpus.
-
-.. note::
-    Please see the :doc:`track reference </track>` for more information on the structure of a track.
+A track describes one or more benchmarking scenarios. Its structure is described in detail in the :doc:`track reference </track>`.
 
 Example track
 -------------
@@ -481,7 +478,7 @@ We changed two things here. First, we imported helper functions from Rally by ad
 
 .. note::
 
-    If you want to check the final result, please check Rally's log file. Rally will print the fully rendered track there after it has loaded it successfully.
+    Rally's log file contains the fully rendered track after it has loaded it successfully.
 
 .. note::
 
@@ -580,7 +577,7 @@ Custom parameter sources
 
 .. warning::
 
-    Your parameter source is on a performance-critical code-path so please double-check with :ref:`Rally's profiling support <clr_enable_driver_profiling>` that you did not introduce any bottlenecks.
+    Your parameter source is on a performance-critical code-path. Double-check with :ref:`Rally's profiling support <clr_enable_driver_profiling>` that you did not introduce any bottlenecks.
 
 
 Consider the following operation definition::
@@ -726,14 +723,14 @@ Let's walk through this code step by step:
     * ``size(self)``: This method is needed to help Rally provide a proper progress indication to users if you use a warmup time period. For bulk indexing, this would return the number of bulks (for a given client). As searches are typically executed with a pre-determined amount of iterations, just return ``1`` in this case.
     * ``params(self)``: This method needs to return a dictionary with all parameters that the corresponding "runner" expects. For the standard case, Rally provides most of these parameters as a convenience, but here you need to define all of them yourself. This method will be invoked once for every iteration during the race. We can see that we randomly select a profession from a list which will be then be executed by the corresponding runner.
 
-For cases, where you want to provide a progress indication but cannot calculate ``size`` up-front (e.g. when you generate bulk requests on-the fly up to a certain total size), you can implement a property ``percent_completed`` which returns a floating point value between ``0.0`` and ``1.0``. Rally will query this value before each call to ``params()`` and uses it for its progress indication. For the implementation, please note:
+For cases, where you want to provide a progress indication but cannot calculate ``size`` up-front (e.g. when you generate bulk requests on-the fly up to a certain total size), you can implement a property ``percent_completed`` which returns a floating point value between ``0.0`` and ``1.0``. Rally will query this value before each call to ``params()`` and uses it for its progress indication. However:
 
 * Rally will not check ``percent_completed``, if it can derive progress in any other way.
 * The value of ``percent_completed`` is purely informational and has no influence whatsoever on when Rally considers an operation to be completed.
 
 .. note::
 
-    Be aware that ``params(self)`` is called on a performance-critical path so don't do anything in this method that takes a lot of time (avoid any I/O). For searches, you should usually throttle throughput anyway and there it does not matter that much but if the corresponding operation is run without throughput throttling, please double-check that you did not introduce a bottleneck in the load test driver with your custom parameter source.
+    Be aware that ``params(self)`` is called on a performance-critical path so don't do anything in this method that takes a lot of time (avoid any I/O). For searches, you should usually throttle throughput anyway and there it does not matter that much but if the corresponding operation is run without throughput throttling, double-check that you did not introduce a bottleneck in the load test driver with your custom parameter source.
 
 In the implementation of custom parameter sources you can access the Python standard API. Using any additional libraries is not supported.
 
@@ -746,7 +743,7 @@ Custom runners
 
 .. warning::
 
-    Your runner is on a performance-critical code-path so please double-check with :ref:`Rally's profiling support <clr_enable_driver_profiling>` that you did not introduce any bottlenecks.
+    Your runner is on a performance-critical code-path. Double-check with :ref:`Rally's profiling support <clr_enable_driver_profiling>` that you did not introduce any bottlenecks.
 
 You cannot only define custom parameter sources but also custom runners. Runners execute an operation against Elasticsearch. Out of the box, Rally supports the following operations:
 
@@ -850,7 +847,7 @@ Custom schedulers
 
 .. warning::
 
-    Your scheduler is on a performance-critical code-path so please double-check with :ref:`Rally's profiling support <clr_enable_driver_profiling>` that you did not introduce any bottlenecks.
+    Your scheduler is on a performance-critical code-path. Double-check with :ref:`Rally's profiling support <clr_enable_driver_profiling>` that you did not introduce any bottlenecks.
 
 If you want to rate-limit execution of tasks, you can specify a ``target-throughput`` (in operations per second). For example, Rally will attempt to run this term query 20 times per second::
 

diff --git a/docs/command_line_reference.rst b/docs/command_line_reference.rst
@@ -160,7 +160,7 @@ Example::
 ``car``
 ~~~~~~~
 
-A :doc:`car </car>` defines the Elasticsearch configuration that will be used for the benchmark. To see a list of possible cars, issue ``esrally list cars``. You can specify one or multiple comma-separated values, for details please refer to the documentation about :doc:`cars </car>`.
+A :doc:`car </car>` defines the Elasticsearch configuration that will be used for the benchmark. To see a list of possible cars, issue ``esrally list cars``. You can specify one or multiple comma-separated values.
 
 **Example**
 
@@ -253,9 +253,9 @@ In this example we can spot quickly that ``Random.seed`` is called excessively,
 ``test-mode``
 ~~~~~~~~~~~~~
 
-Allows you to test a track without running it for the whole duration. This mode is only intended for quick sanity checks when creating a track. Please don't rely on these numbers at all (they are meaningless).
+Allows you to test a track without running it for the whole duration. This mode is only intended for quick sanity checks when creating a track. Don't rely on these numbers at all (they are meaningless).
 
-If you write your own track, please keep in mind that you need :ref:`prepare your track to support this mode <add_track_test_mode>`.
+If you write your own track you need to :ref:`prepare your track to support this mode <add_track_test_mode>`.
 
 ``telemetry``
 ~~~~~~~~~~~~~
@@ -403,7 +403,7 @@ Here are a few common examples:
 * Enable HTTP compression: ``--client-options="compressed:true"``
 * Enable SSL (e.g. if you have X-Pack Security installed): ``--client-options="use_ssl:true,verify_certs:true"``. Note that you don't need to set ``ca_cert`` (which defines the path to the root certificates). Rally does this automatically for you.
 * Enable SSL with a client key and certificate: ``--client-options="use_ssl:true,verify_certs:true,ca_certs:'/path/to/cacert.pem',client_cert:'/path/to/client_cert.pem',client_key='/path/to/client_key.pem"`` (see also the `Elasticsearch Python client docs <http://elasticsearch-py.readthedocs.io/en/master/index.html#ssl-and-authentication>`_)
-* Enable basic authentication: ``--client-options="basic_auth_user:'user',basic_auth_password:'password'"``. Please avoid the characters ``'``, ``,`` and ``:`` in user name and password as Rally's parsing of these options is currently really simple and there is no possibility to escape characters.
+* Enable basic authentication: ``--client-options="basic_auth_user:'user',basic_auth_password:'password'"``. Avoid the characters ``'``, ``,`` and ``:`` in user name and password as Rally's parsing of these options is currently really simple and there is no possibility to escape characters.
 
 ``on-error``
 ~~~~~~~~~~~~

diff --git a/docs/community.rst b/docs/community.rst
@@ -1,7 +1,7 @@
 Community Resources
 ===================
 
-Below are a few community resources about Rally. If you find an interesting article, talk or custom tracks, please `raise an issue <https://github.com/elastic/rally/issues>`_  or `open a pull request <https://github.com/elastic/rally/pulls>`_.
+Below are a few community resources about Rally. If you find an interesting article, talk or custom tracks, `raise an issue <https://github.com/elastic/rally/issues>`_  or `open a pull request <https://github.com/elastic/rally/pulls>`_.
 
 Talks
 -----

diff --git a/docs/configuration.rst b/docs/configuration.rst
@@ -91,7 +91,7 @@ First `install Elasticsearch <https://www.elastic.co/downloads/elasticsearch>`_
 
 .. note::
 
-   Rally will choose the port range 39200-39300 (HTTP) and 39300-39400 (transport) for the benchmark cluster, so please ensure that this port range is not used by the metrics store.
+   Rally will choose the port range 39200-39300 (HTTP) and 39300-39400 (transport) for the benchmark cluster, so do not use this port range for the metrics store.
 
 Optional but recommended is to install also `Kibana <https://www.elastic.co/downloads/kibana>`_. However, note that Kibana will not be auto-configured by Rally.
 
@@ -124,13 +124,11 @@ Hence, it needs to connect via http(s) to the outside world. If you are behind a
 
 Afterwards, source the shell profile with ``source ~/.bash_profile`` and verify that the proxy URL is correctly set with ``echo $http_proxy``.
 
-Finally, you can set up git::
+Finally, you can set up git (see also the `Git config documentation <https://git-scm.com/docs/git-config>`_)::
 
     git config --global http.proxy $http_proxy
 
-For details, please refer to the `Git config documentation <https://git-scm.com/docs/git-config>`_.
-
-Please verify that the proxy setup for git works correctly by cloning any repository, e.g. the ``rally-tracks`` repository::
+Verify that the proxy setup for git works correctly by cloning any repository, e.g. the ``rally-tracks`` repository::
 
     git clone https://github.com/elastic/rally-tracks.git
 

diff --git a/docs/developing.rst b/docs/developing.rst
@@ -4,14 +4,14 @@ Developing Rally
 Prerequisites
 -------------
 
-Please ensure that the following packages are installed before installing Rally in development mode:
+Install the following software packages:
 
 * Python 3.4 or better available as ``python3`` on the path (verify with: ``python3 --version``)
 * ``pip3`` available on the path (verify with ``pip3 --version``)
 * JDK 8 or 9
 * git 1.9 or better
 
-Please check the :doc:`installation guide </install>` for detailed installation instructions for these packages.
+Check the :doc:`installation guide </install>` for detailed installation instructions for these packages.
 
 Rally does not support Windows and is only actively tested on MacOS and Linux.
 
@@ -27,7 +27,7 @@ Installation Instructions for Development
     ./rally
 
 
-If you get errors during installation, it is probably due to the installation of ``psutil`` which we use to gather system metrics like CPU utilization. Please check the `installation instructions of psutil <https://github.com/giampaolo/psutil/blob/master/INSTALL.rst>`_ in this case. Keep in mind that Rally is based on Python 3 and you need to install the Python 3 header files instead of the Python 2 header files on Linux.
+If you get errors during installation, it is probably due to the installation of ``psutil`` which we use to gather system metrics like CPU utilization. Check the `installation instructions of psutil <https://github.com/giampaolo/psutil/blob/master/INSTALL.rst>`_ in this case. Keep in mind that Rally is based on Python 3 and you need to install the Python 3 header files instead of the Python 2 header files on Linux.
 
 Automatic Updates
 ~~~~~~~~~~~~~~~~~
@@ -73,6 +73,4 @@ There is a dedicated :doc:`tutorial on how to add new tracks to Rally</adding_tr
 How to contribute code
 ----------------------
 
-First of all, please read the `contributors guide <https://github.com/elastic/rally/blob/master/CONTRIBUTING.md>`_.
-
-We strive to be PEP-8 compliant but don't follow it to the letter.
+See the `contributors guide <https://github.com/elastic/rally/blob/master/CONTRIBUTING.md>`_. We strive to be PEP-8 compliant but don't follow it to the letter.
diff --git a/docs/elasticsearch_plugins.rst b/docs/elasticsearch_plugins.rst
@@ -74,9 +74,9 @@ You can also override plugin variables with ``--plugin-params`` which is needed
 
     --elasticsearch-plugins="x-pack:monitoring-http" --plugin-params="monitoring_type:'https',monitoring_host:'some_remote_host',monitoring_port:10200,monitoring_user:'rally',monitoring_password:'m0n1t0r1ng'"
 
-The ``monitoring_user`` and ``monitoring_password`` parameters are optional, the other parameters are mandatory. For more details on the configuration options, please see the `Monitoring plugin documentation <https://www.elastic.co/guide/en/x-pack/current/monitoring-production.html>`_.
+The ``monitoring_user`` and ``monitoring_password`` parameters are optional, the other parameters are mandatory. For more details on the configuration options check the `Monitoring plugin documentation <https://www.elastic.co/guide/en/x-pack/current/monitoring-production.html>`_.
 
-If you are behind a proxy, please set the environment variable ``ES_JAVA_OPTS`` accordingly on each target machine as described in the `Elasticsearch plugin documentation <https://www.elastic.co/guide/en/elasticsearch/plugins/current/_other_command_line_parameters.html#_proxy_settings>`_.
+If you are behind a proxy, set the environment variable ``ES_JAVA_OPTS`` accordingly on each target machine as described in the `Elasticsearch plugin documentation <https://www.elastic.co/guide/en/elasticsearch/plugins/current/_other_command_line_parameters.html#_proxy_settings>`_.
 
 Building plugins from sources
 -----------------------------
@@ -110,7 +110,7 @@ In order to run a benchmark with ``my-plugin``, you'd invoke Rally as follows: `
 
 * All prerequisites for source builds are installed.
 * The Elasticsearch source revision is compatible with the chosen plugin revision. Note that you do not need to know the revision hash to build against an already released version and can use git tags instead. E.g. if you want to benchmark against Elasticsearch 5.6.1, you can specify ``--revision="elasticsearch:v5.6.1,my-plugin:some-plugin-revision"`` (see e.g. the `Elasticsearch tags on Github <https://github.com/elastic/elasticsearch/tags>`_ or use ``git tag`` in the Elasticsearch source directory on the console).
-* If your plugin needs to be configured, please ensure to create a proper plugin specification (see below).
+* If your plugin needs to be configured, create a proper plugin specification (see below).
 
 .. note::
     Rally can build all `Elasticsearch core plugins <https://github.com/elastic/elasticsearch/tree/master/plugins>`_ out of the box without any further configuration.
@@ -139,7 +139,7 @@ In order to run a benchmark with ``my-plugin``, you'd invoke Rally as follows: `
 
 * All prerequisites for source builds are installed.
 * The Elasticsearch release is compatible with the chosen plugin revision.
-* If your plugin needs to be configured, please ensure to create a proper plugin specification (see below).
+* If your plugin needs to be configured, create a proper plugin specification (see below).
 
 Anatomy of a plugin specification
 ---------------------------------

diff --git a/docs/faq.rst b/docs/faq.rst
@@ -66,7 +66,7 @@ There are a few more directories but the ones above are the most disk-hogging on
 Does Rally spy on me?
 ---------------------
 
-No. Rally does not collect or send any usage data and also the complete source code is open. We do value your feedback a lot though and if you got any ideas for improvements, found a bug or have any other feedback, please head over to `Rally's Discuss forum <https://discuss.elastic.co/c/elasticsearch/rally>`_ or `raise an issue on Github <https://github.com/elastic/rally>`_.
+No. Rally does not collect or send any usage data and also the complete source code is open. We do value your feedback a lot though and if you got any ideas for improvements, found a bug or have any other feedback, head over to `Rally's Discuss forum <https://discuss.elastic.co/c/elasticsearch/rally>`_ or `raise an issue on Github <https://github.com/elastic/rally>`_.
 
 Do I need an Internet connection?
 ---------------------------------

diff --git a/docs/index.rst b/docs/index.rst
@@ -24,7 +24,8 @@ In general, Rally works with all versions of Elasticsearch starting from 1.x. :d
 Getting Help or Contributing to Rally
 -------------------------------------
 
-Use our `Discuss forum <https://discuss.elastic.co/c/elasticsearch/rally>`_ to provide feedback or ask questions about Rally. Please see our `contribution guide <https://github.com/elastic/rally/blob/master/CONTRIBUTING.md>`_ on guidelines for contributors.
+* Use our `Discuss forum <https://discuss.elastic.co/c/elasticsearch/rally>`_ to provide feedback or ask questions about Rally.
+* See our `contribution guide <https://github.com/elastic/rally/blob/master/CONTRIBUTING.md>`_ on guidelines for contributors.
 
 Source Code
 -----------

diff --git a/docs/install.rst b/docs/install.rst
@@ -11,7 +11,7 @@ Use an SSD on the load generator machine. If you run bulk-indexing benchmarks, R
 Prerequisites
 -------------
 
-Rally does not support Windows and is only actively tested on MacOS and Linux. Before installing Rally, please ensure that the following packages are installed.
+Rally does not support Windows and is only actively tested on MacOS and Linux. Install the following packages first.
 
 Python
 ~~~~~~
@@ -92,7 +92,7 @@ In all other cases, Rally requires ``git 1.9`` or better. Verify with ``git --ve
 
 .. note::
 
-   If you use RHEL, please ensure to install a recent version of git via the `Red Hat Software Collections <https://www.softwarecollections.org/en/scls/rhscl/git19/>`_.
+   If you use RHEL, install a recent version of git via the `Red Hat Software Collections <https://www.softwarecollections.org/en/scls/rhscl/git19/>`_.
 
 **MacOS**
 
@@ -103,7 +103,7 @@ JDK
 
 A JDK is required on all machines where you want to launch Elasticsearch. If you use Rally just as a load generator, no JDK is required.
 
-We recommend to use Oracle JDK but you are free to use OpenJDK as well. For details on how to install a JDK, please see your operating system's documentation pages.
+We recommend to use Oracle JDK but you are free to use OpenJDK as well. For details on how to install a JDK check your operating system's documentation pages.
 
 
 .. note::
@@ -119,7 +119,7 @@ Simply install Rally with pip: ``pip3 install esrally``
 
    Depending on your system setup you may need to prepend this command with ``sudo``.
 
-If you get errors during installation, it is probably due to the installation of ``psutil`` which we use to gather system metrics like CPU utilization. Please ensure that you have installed the Python development package as documented in the prerequisites section above.
+If you get errors during installation, it is probably due to the installation of ``psutil`` which we use to gather system metrics like CPU utilization. Ensure that you have installed the Python development package as documented in the prerequisites section above.
 
 Non-sudo Install
 ----------------

diff --git a/docs/metrics.rst b/docs/metrics.rst
@@ -57,7 +57,7 @@ track, track-params, challenge, car
 
 This is the track, challenge and car for which the metrics record has been produced. If the user has provided track parameters with the command line parameter, ``--track-params``, each of them is listed here too.
 
-If you specify a car with mixins, it will be stored as one string separated with "+", e.g. ``--car="4gheap,ea"`` will be stored as ``4gheap+ea`` in the metrics store in order to simplify querying in Kibana. For more details, please see the :doc:`cars </car>` documentation.
+If you specify a car with mixins, it will be stored as one string separated with "+", e.g. ``--car="4gheap,ea"`` will be stored as ``4gheap+ea`` in the metrics store in order to simplify querying in Kibana. Check the :doc:`cars </car>` documentation for more details.
 
 sample-type
 ~~~~~~~~~~~