diff --git a/README.rst b/README.rst
index 26e7723..1621ce9 100644
--- a/README.rst
+++ b/README.rst
@@ -1,18 +1,16 @@
 
-===============
-Reclass Formula
-===============
+=====
+Usage
+=====
 
-reclass is an "external node classifier" (ENC) as can be used with automation
+Reclass is an external node classifier (ENC) as can be used with automation
 tools, such as Puppet, Salt, and Ansible. It is also a stand-alone tool for
 merging data sources recursively.
 
-
 Sample Metadata
 ===============
 
-Install sources from [repository, git, pip]
-
+Install sources from [repository, git, pip]:
 
 .. code-block:: yaml
 
@@ -29,7 +27,7 @@
         engine: pip
     ...
 
-If reclass is pre-installed, set the engine to None to avoid updates.
+If reclass is pre-installed, set the engine to None to avoid updates:
 
 .. code-block:: yaml
 
@@ -37,53 +35,61 @@
       source:
         engine: None
 
+Reclass storage with data fetched from git:
 
-Reclass storage with data fetched from git
+.. code-block:: yaml
 
-.. literalinclude:: tests/pillar/storage_git.sls
-   :language: yaml
+   See tests/pillar/storage_git.sls
 
-Reclass storage with local data source
+Reclass storage with local data source:
 
-.. literalinclude:: tests/pillar/storage_local.sls
-   :language: yaml
+.. code-block:: yaml
 
-Reclass storage with archive data source
+   See tests/pillar/storage_local.sls
 
-.. literalinclude:: tests/pillar/storage_archive.sls
-   :language: yaml
+Reclass storage with archive data source:
 
-Reclass storage with archive data source with content hash check
+.. code-block:: yaml
 
-.. literalinclude:: tests/pillar/storage_archive_public.sls
-   :language: yaml
+   See tests/pillar/storage_archive.sls
 
-Reclass model with single node definition
+Reclass storage with archive data source with content hash check:
 
-.. literalinclude:: tests/pillar/generate_single.sls
-   :language: yaml
+.. code-block:: yaml
 
-Reclass model with multiple node defined
+   See tests/pillar/storage_archive_public.sls
 
-.. literalinclude:: tests/pillar/generate_multi.sls
-   :language: yaml
+Reclass model with single node definition:
 
-Reclass model with multiple node defined and interpolation enabled
+.. code-block:: yaml
 
-.. literalinclude:: tests/pillar/generate_multi_interpolate.sls
-   :language: yaml
+   See tests/pillar/generate_single.sls
 
-Reclass storage with simple class mappings
+Reclass model with multiple node defined:
 
-.. literalinclude:: tests/pillar/class_mapping.sls
-   :language: yaml
+.. code-block:: yaml
+
+   See tests/pillar/generate_multi.sls
+
+Reclass model with multiple node defined and interpolation enabled:
+
+.. code-block:: yaml
+
+   See tests/pillar/generate_multi_interpolate.sls
+
+Reclass storage with simple class mappings:
+
+.. code-block:: yaml
+
+   See tests/pillar/class_mapping.sls
 
 Reclass models with dynamic node classification
 
-.. literalinclude:: tests/pillar/node_classify.sls
-   :language: yaml
+.. code-block:: yaml
 
-Classify node after creation and unclassify on node deletion
+   See tests/pillar/node_classify.sls
+
+Classify node after creation and unclassify on node deletion:
 
 .. code-block:: yaml
 
@@ -95,7 +101,7 @@
           reclass/minion/declassify:
           - salt://reclass/reactor/node_unregister.sls
 
-Event to trigger the node classification
+Event to trigger the node classification:
 
 .. code-block:: bash
 
@@ -110,25 +116,31 @@
 
 Confirmation of node classification
 
-    Currently salt doesn't allow to get confirmation on minion upon successfull reactor execution on event. However there can be issues
-    with reactor in salt 2017.7 (https://github.com/saltstack/salt/issues/47539) or reactor register state can fail if pillar failed
-    to render, so node registration confirmation maybe needed. In order to enable this functionality add node_confirm_registration parameter to
-    event data with value true:
+Currently, Salt does not allow getting confirmation on minion upon successful
+reactor execution on event. However, there can be issues with reactor in Salt
+2017.7 (https://github.com/saltstack/salt/issues/47539) or reactor register
+state can fail if pillar failed to render, so node registration confirmation
+may be needed. To enable this functionality, add the
+``node_confirm_registration`` parameter to event data with value ``true``:
 
 .. code-block:: bash
 
-    salt-call event.send 'reclass/minion/classify' "{'node_master_ip': '$config_host', 'node_ip': '${node_ip}', 'node_domain': '$node_domain', 'node_cluster': '$node_cluster', 'node_hostname': '$node_hostname', 'node_os': '$node_os', node_confirm_registration: true}"
+   salt-call event.send 'reclass/minion/classify' "{'node_master_ip': '$config_host', 'node_ip': '${node_ip}', 'node_domain': '$node_domain', 'node_cluster': '$node_cluster', 'node_hostname': '$node_hostname', 'node_os': '$node_os', node_confirm_registration: true}"
 
-    Then on minion side execute:
-      salt-call mine.get 'salt:master' ${minion_id}_classified pillar
-
-    If true is returned than registration has passed successfully
-
-Event to trigger the node declassification
+Then on minion side execute:
 
 .. code-block:: bash
 
-    salt-call event.send 'reclass/minion/declassify'
+   salt-call mine.get 'salt:master' ${minion_id}_classified pillar
+
+If ``true`` is returned, then registration has passed successfully.
+
+
+Event to trigger the node declassification:
+
+.. code-block:: bash
+
+   salt-call event.send 'reclass/minion/declassify'
 
 Nodes definitions generator
 ===========================
@@ -190,7 +202,9 @@
                   start: 101
                   value: 192.168.2.<<count>>
 
-Multiple nodes definitions (using generator) with IP address comprehension. Ranges are named and formatting symbol of the same name is replaced by IP address from corresponding range:
+Multiple nodes definitions (using generator) with IP address comprehension.
+Ranges are named and formatting symbol of the same name is replaced by IP
+address from the corresponding range:
 
 .. code-block:: yaml
 
@@ -221,42 +235,34 @@
                   start: 101
                   value: 192.168.2.<<tenant_address>>
 
-More Information
-================
+Read more
+=========
 
 * http://reclass.pantsfullofunix.net/index.html
 * http://reclass.pantsfullofunix.net/operations.html
 
-
 Documentation and Bugs
 ======================
 
-To learn how to install and update salt-formulas, consult the documentation
-available online at:
+* http://salt-formulas.readthedocs.io/
+   Learn how to install and update salt-formulas
 
-    http://salt-formulas.readthedocs.io/
+* https://github.com/salt-formulas/salt-formula-reclass/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 issue tracker. Use Github issue tracker for specific salt
-formula:
+* https://launchpad.net/salt-formulas
+   For feature requests, bug reports, or blueprints affecting the entire
+   ecosystem, use the Launchpad salt-formulas project
 
-    https://github.com/salt-formulas/salt-formula-reclass/issues
+* https://launchpad.net/~salt-formulas-users
+   Join the salt-formulas-users team and subscribe to mailing list if required
 
-For feature requests, bug reports or blueprints affecting entire ecosystem,
-use Launchpad salt-formulas project:
+* https://github.com/salt-formulas/salt-formula-reclass
+   Develop the salt-formulas projects in the master branch and then submit pull
+   requests against a specific formula
 
-    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-reclass
-
-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