diff --git a/README.rst b/README.rst
index 1153f2f..0d49ea7 100644
--- a/README.rst
+++ b/README.rst
@@ -1,12 +1,11 @@
-==============
-Glance formula
-==============
+=====
+Usage
+=====
 
 The Glance project provides services for discovering, registering, and
 retrieving virtual machine images. Glance has a RESTful API that allows
 querying of VM image metadata as well as retrieval of the actual image.
 
-
 Sample pillars
 ==============
 
@@ -59,16 +58,17 @@
         barbican:
           enabled: true
 
-The pagination is controlled by the *api_limit_max* and *limit_param_default*
+The pagination is controlled by the ``api_limit_max`` and ``limit_param_default``
 parameters as shown above:
 
-* *api_limit_max* defines the maximum number of records that the server will
-  return.
+* ``api_limit_max``
+   Defines the maximum number of records that the server will return.
 
-* *limit_param_default* is the default *limit* parameter that
-  applies if the request didn't defined it explicitly.
+* ``limit_param_default``
+   The default ``limit`` parameter that applies if the request didn't define
+   it explicitly.
 
-Configuration of policy.json file
+Configuration of the ``policy.json`` file:
 
 .. code-block:: yaml
 
@@ -79,6 +79,7 @@
           publicize_image: "role:admin"
           # Add key without value to remove line from policy.json
           add_member:
+
 Keystone and cinder region
 
 .. code-block:: yaml
@@ -170,62 +171,57 @@
 Configuring TLS communications
 ------------------------------
 
-
-**Note:** by default system wide installed CA certs are used, so ``cacert_file`` param is optional, as well as ``cacert``.
-
+.. 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
+  .. code-block:: yaml
 
- glance:
-   server:
-      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
-
+   glance:
+     server:
+        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
 
 - **MySQL TLS**
 
-.. code-block:: yaml
+  .. code-block:: yaml
 
- glance:
-   server:
-      database:
-        ssl:
-          enabled: True
-          (optional) cacert: cert body if the cacert_file does not exists
-          (optional) cacert_file: /etc/openstack/mysql-ca.pem
+   glance:
+     server:
+        database:
+          ssl:
+            enabled: True
+            (optional) cacert: cert body if the cacert_file does not exists
+            (optional) cacert_file: /etc/openstack/mysql-ca.pem
 
 - **Openstack HTTPS API**
 
+  Set the ``https`` as protocol at ``glance:server`` sections:
 
-Set the ``https`` as protocol at ``glance:server`` sections:
+  .. code-block:: yaml
 
-.. code-block:: yaml
-
- glance:
-   server:
-      identity:
-         protocol: https
-         (optional) cacert_file: /etc/openstack/proxy.pem
-      registry:
-         protocol: https
-         (optional) cacert_file: /etc/openstack/proxy.pem
-      storage:
-         engine: cinder, swift
-         cinder:
-            protocol: https
+   glance:
+     server:
+        identity:
+           protocol: https
            (optional) cacert_file: /etc/openstack/proxy.pem
-         swift:
-            store:
-                (optional) cafile: /etc/openstack/proxy.pem
-
-
+        registry:
+           protocol: https
+           (optional) cacert_file: /etc/openstack/proxy.pem
+        storage:
+           engine: cinder, swift
+           cinder:
+              protocol: https
+             (optional) cacert_file: /etc/openstack/proxy.pem
+           swift:
+              store:
+                  (optional) cafile: /etc/openstack/proxy.pem
 
 Enable Glance Image Cache:
 
@@ -275,7 +271,8 @@
               user: 2ec7966596504f59acc3a76b3b9d9291:glance-user
               key: someRandomPassword
 
-Another way, which also supports multiple swift backends, can be configured like this:
+Another way, which also supports multiple swift backends, can be
+configured like this:
 
 .. code-block:: yaml
 
@@ -299,7 +296,7 @@
                   user: 2ec7966596504f59acc3a76b3b9d9291:glance-user
                   key: someRandomPassword
 
-Enable CORS parameters
+Enable CORS parameters:
 
 .. code-block:: yaml
 
@@ -315,6 +312,7 @@
 
 Enable Viewing Multiple Locations
 ---------------------------------
+
 If you want to expose all locations available (for example when you have
 multiple backends configured), then you can configure this like so:
 
@@ -326,12 +324,12 @@
         location_strategy: store_type
         store_type_preference: rbd,swift,file
 
-Please note: the show_multiple_locations option is deprecated since Newton and is planned
-             to be handled by policy files _only_ starting with the Pike release.
+.. note:: The ``show_multiple_locations`` option is deprecated since
+          Newton and is planned to be handled by policy files *only*
+          starting with the Pike release.
 
-This feature is convenient in a scenario when you have swift and rbd configured and want to
-benefit from rbd enhancements.
-
+This feature is convenient in a scenario when you have swift and rbd
+configured and want to benefit from rbd enhancements.
 
 Barbican integration glance
 ---------------------------
@@ -368,13 +366,20 @@
 By default logging.conf is disabled.
 
 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.
 
-Only WatchedFileHandler, OSSysLogHandler and FluentHandler are available.
+* ``openstack_log_appender``
+   Set to true to enable ``log_config_append`` for all OpenStack services
 
-Also it is possible to configure this with pillar:
+* ``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
+
+Only ``WatchedFileHandler``, ``OSSysLogHandler``, and ``FluentHandler``
+are available.
+
+Also, it is possible to configure this with pillar:
 
 .. code-block:: yaml
 
@@ -393,86 +398,53 @@
 Usage
 =====
 
-Import new public image
+#. Import new public image:
 
-.. code-block:: yaml
+   .. code-block:: yaml
 
     glance image-create --name 'Windows 7 x86_64' --is-public true --container-format bare --disk-format qcow2  < ./win7.qcow2
 
-Change new image's disk properties
+#. Change new image's disk properties
 
-.. code-block:: yaml
+   .. code-block:: yaml
 
     glance image-update "Windows 7 x86_64" --property hw_disk_bus=ide
 
-Change new image's NIC properties
+#. Change new image's NIC properties
 
-.. code-block:: yaml
+   .. code-block:: yaml
 
     glance image-update "Windows 7 x86_64" --property hw_vif_model=rtl8139
 
 
-External links
-==============
+Read more
+==========
 
 * http://ceph.com/docs/master/rbd/rbd-openstack/
 
-
 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-glance/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-glance
+   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-glance
+* #salt-formulas @ irc.freenode.net
+   Use this IRC channel in case of any questions or feedback which is always
+   welcome
 
-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-glance/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-glance
-
-Any questions or feedback is always welcome so feel free to join our IRC
-channel:
-
-    #salt-formulas @ irc.freenode.net