diff --git a/README.rst b/README.rst
index fbdaaf9..5e1f645 100644
--- a/README.rst
+++ b/README.rst
@@ -1,18 +1,21 @@
-==============================
-Openstack Cinder Block Storage
-==============================
+=====
+Usage
+=====
 
-Cinder provides an infrastructure for managing volumes in OpenStack. It was
-originally a Nova component called nova-volume, but has become an independent
-project since the Folsom release.
+Cinder provides an infrastructure for managing volumes in OpenStack.
+Originally, this project was the Nova component called ``nova-volume``
+and starting from the Folsom OpenStack release it has become an independent
+project.
 
-Sample pillars
-==============
+This file provides the sample configurations for different use cases:
 
-New structure divides cinder-api,cinder-scheduler to role controller and
-cinder-volume to role volume.
+* Pillar sample of a basic Cinder configuration:
 
-.. code-block:: yaml
+  The pillar structure defines ``cinder-api`` and ``cinder-scheduler`` inside
+  the ``controller`` role and ``cinder-volume`` inside the to ``volume``
+  role.
+
+  .. code-block:: yaml
 
     cinder:
       controller:
@@ -116,10 +119,9 @@
         barbican:
           enabled: true
 
+* The CORS parameters enablement:
 
-Enable CORS parameters
-
-.. code-block:: yaml
+  .. code-block:: yaml
 
     cinder:
       controller:
@@ -131,95 +133,91 @@
           allow_credentials: True
           max_age: 86400
 
-Client-side RabbitMQ HA setup for controller
+* The client-side RabbitMQ HA setup for the controller:
 
-.. code-block:: yaml
+  .. code-block:: yaml
 
-    cinder:
-      controller:
-        ....
-        message_queue:
-          engine: rabbitmq
-          members:
-            - host: 10.0.16.1
-            - host: 10.0.16.2
-            - host: 10.0.16.3
-          user: openstack
-          password: pwd
-          virtual_host: '/openstack'
-        ....
+      cinder:
+        controller:
+          ....
+          message_queue:
+            engine: rabbitmq
+            members:
+              - host: 10.0.16.1
+              - host: 10.0.16.2
+              - host: 10.0.16.3
+            user: openstack
+            password: pwd
+            virtual_host: '/openstack'
+          ....
 
-Client-side RabbitMQ HA setup for volume component
+* The client-side RabbitMQ HA setup for the volume component
 
-.. code-block:: yaml
+  .. code-block:: yaml
 
-    cinder:
-      volume:
-        ....
-        message_queue:
-          engine: rabbitmq
-          members:
-            - host: 10.0.16.1
-            - host: 10.0.16.2
-            - host: 10.0.16.3
-          user: openstack
-          password: pwd
-          virtual_host: '/openstack'
-        ....
+     cinder:
+       volume:
+         ....
+         message_queue:
+           engine: rabbitmq
+           members:
+             - host: 10.0.16.1
+             - host: 10.0.16.2
+             - host: 10.0.16.3
+           user: openstack
+           password: pwd
+           virtual_host: '/openstack'
+         ....
 
 
-Configuring TLS communications
-------------------------------
+* Configuring TLS communications.
 
+  .. note:: By default, system-wide installed CA certs are used.
+            Therefore, the ``cacert_file`` and ``cacert`` parameters are
+            optional.
 
-**Note:** by default system wide installed CA certs are used, so ``cacert_file`` param is optional, as well as ``cacert``.
+  * RabbitMQ TLS:
 
+    .. code-block:: yaml
 
-- **RabbitMQ TLS**
+       cinder:
+         controller, volume:
+            message_queue:
+              port: 5671
+              ssl:
+                enabled: True
+                (optional) cacert: cert body if the cacert_file does not exists
+                (optional) cacert_file: /etc/openstack/rabbitmq-ca.pem
+                (optional) version: TLSv1_2
 
-.. code-block:: yaml
+  * MySQL TLS:
 
- cinder:
-   controller, volume:
-      message_queue:
-        port: 5671
-        ssl:
-          enabled: True
-          (optional) cacert: cert body if the cacert_file does not exists
-          (optional) cacert_file: /etc/openstack/rabbitmq-ca.pem
-          (optional) version: TLSv1_2
+    .. code-block:: yaml
 
+       cinder:
+         controller:
+            database:
+              ssl:
+                enabled: True
+                (optional) cacert: cert body if the cacert_file does not exists
+                (optional) cacert_file: /etc/openstack/mysql-ca.pem
 
-- **MySQL TLS**
+  * Openstack HTTPS API:
 
-.. code-block:: yaml
+    .. code-block:: yaml
 
- cinder:
-   controller:
-      database:
-        ssl:
-          enabled: True
-          (optional) cacert: cert body if the cacert_file does not exists
-          (optional) cacert_file: /etc/openstack/mysql-ca.pem
+       cinder:
+        controller, volume:
+            identity:
+               protocol: https
+               (optional) cacert_file: /etc/openstack/proxy.pem
+            glance:
+               protocol: https
+               (optional) cacert_file: /etc/openstack/proxy.pem
 
-- **Openstack HTTPS API**
+* Cinder setup with zeroing deleted volumes:
 
-.. code-block:: yaml
-
- cinder:
-  controller, volume:
-      identity:
-         protocol: https
-         (optional) cacert_file: /etc/openstack/proxy.pem
-      glance:
-         protocol: https
-         (optional) cacert_file: /etc/openstack/proxy.pem
-
-
-
-Cinder setup with zeroing deleted volumes
-
-.. code-block:: yaml
+  .. code-block:: yaml
 
     cinder:
       controller:
@@ -227,9 +225,9 @@
         wipe_method: zero
         ...
 
-Cinder setup with shreding deleted volumes
+* Cinder setup with shreding deleted volumes:
 
-.. code-block:: yaml
+  .. code-block:: yaml
 
     cinder:
       controller:
@@ -237,9 +235,9 @@
         wipe_method: shred
         ...
 
-Configuration of policy.json file
+* Configuration of ``policy.json`` file:
 
-.. code-block:: yaml
+  .. code-block:: yaml
 
     cinder:
       controller:
@@ -249,9 +247,9 @@
           # Add key without value to remove line from policy.json
           'volume:extend':
 
-Default Cinder backend lvm_type setup
+* Default Cinder backend ``lvm_type`` setup:
 
-.. code-block:: yaml
+  .. code-block:: yaml
 
     cinder:
       volume:
@@ -260,10 +258,9 @@
           # Type of LVM volumes to deploy; (default, thin, or auto). Auto defaults to thin if thin is supported.
           lvm_type: auto
 
+* Default Cinder setup with iSCSI target:
 
-Default Cinder setup with iSCSI target
-
-.. code-block:: yaml
+  .. code-block:: yaml
 
     cinder:
       controller:
@@ -297,9 +294,9 @@
             type_name: lvmdriver-1
             volume_group: cinder-volume
 
-Cinder setup for IBM Storwize
+* Cinder setup for IBM Storwize:
 
-.. code-block:: yaml
+  .. code-block:: yaml
 
     cinder:
       volume:
@@ -339,10 +336,9 @@
             multipath: true
             pool: SAS15K
 
+* Cinder setup with NFS:
 
-Cinder setup with NFS
-
-.. code-block:: yaml
+  .. code-block:: yaml
 
     cinder:
       controller:
@@ -358,10 +354,9 @@
             - 172.16.10.110:/var/nfs/cinder
             options: rw,sync
 
+* Cinder setup with NetApp:
 
-Cinder setup with NetApp
-
-.. code-block:: yaml
+  .. code-block:: yaml
 
     cinder:
       controller:
@@ -390,10 +385,9 @@
           nfs-common:
             version: latest
 
+* Cinder setup with Hitachi VPS:
 
-Cinder setup with Hitachi VPS
-
-.. code-block:: yaml
+  .. code-block:: yaml
 
     cinder:
       controller:
@@ -405,9 +399,9 @@
             engine: hitachi_vsp
             connection: FC
 
-Cinder setup with Hitachi VPS with defined ldev range
+* Cinder setup with Hitachi VPS with defined ``ldev`` range:
 
-.. code-block:: yaml
+  .. code-block:: yaml
 
     cinder:
       controller:
@@ -420,30 +414,29 @@
             connection: FC
             ldev_range: 0-1000
 
-Cinder setup with CEPH
+* Cinder setup with Ceph:
 
-.. code-block:: yaml
+  .. code-block:: yaml
 
-    cinder:
-      controller:
-        enabled: true
-        backend:
-          ceph_backend:
-            type_name: standard-iops
-            backend: ceph_backend
-            pool: volumes
-            engine: ceph
-            user: cinder
-            secret_uuid: da74ccb7-aa59-1721-a172-0006b1aa4e3e
-            client_cinder_key: AQDOavlU6BsSJhAAnpFR906mvdgdfRqLHwu0Uw==
-            report_discard_supported: True
+      cinder:
+        controller:
+          enabled: true
+          backend:
+            ceph_backend:
+              type_name: standard-iops
+              backend: ceph_backend
+              pool: volumes
+              engine: ceph
+              user: cinder
+              secret_uuid: da74ccb7-aa59-1721-a172-0006b1aa4e3e
+              client_cinder_key: AQDOavlU6BsSJhAAnpFR906mvdgdfRqLHwu0Uw==
+              report_discard_supported: True
 
-http://ceph.com/docs/master/rbd/rbd-openstack/
+  .. note:: `Ceph official documentation <http://ceph.com/docs/master/rbd/rbd-openstack/>`__
 
+* Cinder setup with HP3par:
 
-Cinder setup with HP3par
-
-.. code-block:: yaml
+  .. code-block:: yaml
 
     cinder:
       controller:
@@ -462,9 +455,9 @@
             debug: True
             snapcpg: OpenStackSNAPCPG
 
-Cinder setup with Fujitsu Eternus
+* Cinder setup with Fujitsu Eternus:
 
-.. code-block:: yaml
+  .. code-block:: yaml
 
     cinder:
       volume:
@@ -491,9 +484,9 @@
             connection: FC/iSCSI
             name: 10k_SAS
 
-Cinder setup with IBM GPFS filesystem
+* Cinder setup with IBM GPFS filesystem:
 
-.. code-block:: yaml
+  .. code-block:: yaml
 
     cinder:
       volume:
@@ -508,9 +501,9 @@
             engine: gpfs
             mount_point: '/mnt/gpfs-openstack/cinder/silver'
 
-Cinder setup with HP LeftHand
+* Cinder setup with HP LeftHand:
 
-.. code-block:: yaml
+  .. code-block:: yaml
 
     cinder:
       volume:
@@ -525,15 +518,15 @@
             clustername: cluster1
             iscsi_chap_enabled: false
 
-Extra parameters for HP LeftHand
+* Extra parameters for HP LeftHand:
 
-.. code-block:: yaml
+  .. code-block:: yaml
 
     cinder type-key normal-storage set hplh:data_pl=r-10-2 hplh:provisioning=full
 
-Cinder setup with Solidfire
+* Cinder setup with Solidfire:
 
-.. code-block:: yaml
+  .. code-block:: yaml
 
     cinder:
       volume:
@@ -550,9 +543,9 @@
             sf_api_port: 14443
             host: ctl01
 
-Cinder setup with Block Device driver
+* Cinder setup with Block Device driver:
 
-.. code-block:: yaml
+  .. code-block:: yaml
 
     cinder:
       volume:
@@ -567,9 +560,9 @@
               - sdc
               - sdd
 
-Enable cinder-backup service for ceph
+* Enable cinder-backup service for ceph
 
-.. code-block:: yaml
+  .. code-block:: yaml
 
     cinder:
       controller:
@@ -597,9 +590,9 @@
           ceph_chunk_size: 134217728
           restore_discard_excess_bytes: false
 
-Enable auditing filter, ie: CADF
+* Auditing filter (CADF) enablement:
 
-.. code-block:: yaml
+  .. code-block:: yaml
 
     cinder:
       controller:
@@ -616,10 +609,9 @@
           filter_factory: 'keystonemiddleware.audit:filter_factory'
           map_file: '/etc/pycadf/cinder_api_audit_map.conf'
 
+* Cinder setup with custom availability zones:
 
-Cinder setup with custom availability zones:
-
-.. code-block:: yaml
+  .. code-block:: yaml
 
     cinder:
       controller:
@@ -630,10 +622,16 @@
         default_availability_zone: my-default-zone
         storage_availability_zone: my-custom-zone-name
 
+  The ``default_availability_zone`` is used when a volume has been created,
+  without specifying a zone in the ``create`` request as this zone must exist
+  in your configuration.
 
-Cinder setup with custom non-admin volume query filters:
+  The ``storage_availability_zone`` is an actual zone where the node belongs to
+  and must be specified per each node.
 
-.. code-block:: yaml
+* Cinder setup with custom non-admin volume query filters:
+
+  .. code-block:: yaml
 
     cinder:
       controller:
@@ -644,26 +642,25 @@
           - availability_zone
           - bootable
 
+* ``public_endpoint`` and ``osapi_volume_base_url``:
 
-public_endpoint and osapi_volume_base_url parameters:
-"public_endpoint" is used for configuring versions endpoint,
-"osapi_volume_base_URL" is used to present Cinder URL to users.
-They are useful when running Cinder under load balancer in SSL.
+  * ``public_endpoint``
+     Used for configuring versions endpoint
+  * ``osapi_volume_base_URL``
+     Used to present Cinder URL to users
 
-.. code-block:: yaml
+  These parameters can be useful when running Cinder under load balancer in
+  SSL.
+
+  .. code-block:: yaml
 
     cinder:
       controller:
         public_endpoint_address: https://${_param:cluster_domain}:8776
 
-The default availability zone is used when a volume has been created, without specifying a zone in the create request. (this zone must exist in your configuration obviously)
-The storage availability zone is the actual zone where the node belongs to. Make sure to specify this per node.
-Check the documentation of OpenStack for more information
+* Client role definition:
 
-
-Client role
-
-.. code-block:: yaml
+  .. code-block:: yaml
 
     cinder:
       client:
@@ -684,38 +681,43 @@
             key:
               conn_speed: fibre-10G
 
-Enable Barbican integration
+* Barbican integration enablement:
 
-.. code-block:: yaml
+  .. code-block:: yaml
 
     cinder:
       controller:
         barbican:
           enabled: true
 
+* Keystone API version specification (v3 is default):
 
-Specify Keystone API version (v3 is default):
-
-.. code-block:: yaml
+  .. code-block:: yaml
 
     cinder:
       controller:
         identity:
           api_version: v2.0
 
-Enhanced logging with logging.conf
-----------------------------------
+**Enhanced logging with logging.conf**
 
-By default logging.conf is disabled.
+By default ``logging.conf`` is disabled.
+You can enable per-binary ``logging.conf`` by setting the following
+parameters:
 
-That is possible to enable per-binary logging.conf with new variables:
-  * openstack_log_appender - set it to true to enable log_config_append for all OpenStack services;
-  * openstack_fluentd_handler_enabled - set to true to enable FluentHandler for all Openstack services.
-  * openstack_ossyslog_handler_enabled - set to true to enable OSSysLogHandler for all Openstack services.
+* ``openstack_log_appender``
+   Set to ``true`` to enable ``log_config_append`` for all OpenStack
+   services
 
-Only WatchedFileHandler, OSSysLogHandler and FluentHandler are available.
+* ``openstack_fluentd_handler_enabled``
+   Set to ``true`` to enable FluentHandler for all Openstack services
 
-Also it is possible to configure this with pillar:
+* ``openstack_ossyslog_handler_enabled``
+   Set to ``true`` to enable OSSysLogHandler for all Openstack services
+
+Only WatchedFileHandler, OSSysLogHandler, and FluentHandler are available.
+
+To configure this functionality with pillar:
 
 .. code-block:: yaml
 
@@ -742,61 +744,27 @@
           ossyslog:
             enabled: true
 
-Documentation and Bugs
-============================
+**Documentation and bugs**
 
-To learn how to deploy OpenStack Salt, consult the documentation available
-online at:
+* http://salt-formulas.readthedocs.io/
+   Learn how to install and update salt-formulas
 
-https://wiki.openstack.org/wiki/OpenStackSalt
+* https://github.com/salt-formulas/salt-formula-cinder/issues
+   In the unfortunate event that bugs are discovered, report the issue to the
+   appropriate issue tracker. Use the Github issue tracker for a specific salt
+   formula
 
-In the unfortunate event that bugs are discovered, they should be reported to
-the appropriate bug tracker. If you obtained the software from a 3rd party
-operating system vendor, it is often wise to use their own bug tracker for
-reporting problems. In all other cases use the master OpenStack bug tracker,
-available at:
+* https://launchpad.net/salt-formulas
+   For feature requests, bug reports, or blueprints affecting the entire
+   ecosystem, use the Launchpad salt-formulas project
 
-    http://bugs.launchpad.net/openstack-salt
+* https://launchpad.net/~salt-formulas-users
+   Join the salt-formulas-users team and subscribe to mailing list if required
 
-Developers wishing to work on the OpenStack Salt project should always base
-their work on the latest formulas code, available from the master GIT
-repository at:
+* https://github.com/salt-formulas/salt-formula-cinder
+   Develop the salt-formulas projects in the master branch and then submit pull
+   requests against a specific formula
 
-    https://git.openstack.org/cgit/openstack/salt-formula-cinder
-
-Developers should also join the discussion on the IRC list, at:
-
-    https://wiki.openstack.org/wiki/Meetings/openstack-salt
-
-Documentation and Bugs
-======================
-
-To learn how to install and update salt-formulas, consult the documentation
-available online at:
-
-    http://salt-formulas.readthedocs.io/
-
-In the unfortunate event that bugs are discovered, they should be reported to
-the appropriate issue tracker. Use Github issue tracker for specific salt
-formula:
-
-    https://github.com/salt-formulas/salt-formula-cinder/issues
-
-For feature requests, bug reports or blueprints affecting entire ecosystem,
-use Launchpad salt-formulas project:
-
-    https://launchpad.net/salt-formulas
-
-You can also join salt-formulas-users team and subscribe to mailing list:
-
-    https://launchpad.net/~salt-formulas-users
-
-Developers wishing to work on the salt-formulas projects should always base
-their work on master branch and submit pull request against specific formula.
-
-    https://github.com/salt-formulas/salt-formula-cinder
-
-Any questions or feedback is always welcome so feel free to join our IRC
-channel:
-
-    #salt-formulas @ irc.freenode.net
+* #salt-formulas @ irc.freenode.net
+   Use this IRC channel in case of any questions or feedback which is always
+   welcome