diff --git a/doc/source/openstack_architecture_model.md b/doc/source/openstack_architecture_model.rst
similarity index 81%
rename from doc/source/openstack_architecture_model.md
rename to doc/source/openstack_architecture_model.rst
index 2afc27b..da898d5 100644
--- a/doc/source/openstack_architecture_model.md
+++ b/doc/source/openstack_architecture_model.rst
@@ -1,5 +1,6 @@
 Architecture Data Model
 =======================
+
 Overview
 --------
 
@@ -9,13 +10,13 @@ necessary to inspect, analyze, describe and visualize OpenStack architecture.
 Architecture data model serves multiple actual and potential use cases.
 
 Diagnostics
------------
+^^^^^^^^^^^
 
 Architecture data model provides necessary data for the configuration analysis
-and diagnostics tool ('''Rubick''').
+and diagnostics tool (**Rubick**).
 
 Deployment
-----------
+^^^^^^^^^^
 
 Arhictecture data model must include all information necessary to deployment
 systems (e.g. **Fuel** or **TripleO**). We will implement simple conversion
@@ -23,39 +24,39 @@ tools which will allow to configure these deployment systems and effectively
 support 'portable' clouds.
 
 Benchmarking
-------------
+^^^^^^^^^^^^
 
-This model could be reused by '''Rally''' project to compare benchmarking
+This model could be reused by **Rally** project to compare benchmarking
 results for different architectures. Definitions of architectures must be
 comparable and portable, which is exactly what architecture model aimed to
 solve.
 
 Upgrade
--------
+^^^^^^^
 
 Upgrade system could potentially utilize the model just in the way the
 Deployment systems do. In addition, existing clouds could be inspected and
 described for subsequent upgrade using this model.
 
 Tech Support
-------------
+^^^^^^^^^^^^
 
 The model suits as base for questionaire to assess existing installations for
 support contract pricing purposes.
 
 Hardening
----------
+^^^^^^^^^
 
 The model could be used to perform automated/guided hardening of OpenStack
 architecture and configuration. This is achieved through use of 'best practice'
 rulesets for the inspection of cloud.
 
 Expert system
--------------
+^^^^^^^^^^^^^
 
-The model could be used as a part of production rules system capable of
-automated reporting and handling of operational errors, based on combination of
-'base' status of the cloud, logging messages and notifications.
+The model could be used as a part of production/reactive rules system capable
+of automated reporting and handling of operational errors, based on combination
+of *base* status of the cloud, logging messages and notifications.
 
 Data Format
 -----------
@@ -65,7 +66,7 @@ installation. The model includes data regarding physical infrastructure, logical
 topology of services and mapping between the two.
 
 Architecture data model could be serialized as JSON or YaML document of the
-following format:
+following format::
 
     openstack
         nodes
diff --git a/doc/source/openstack_diagnostics_proposal.rst b/doc/source/openstack_diagnostics_proposal.rst
index c8be854..5effb3a 100644
--- a/doc/source/openstack_diagnostics_proposal.rst
+++ b/doc/source/openstack_diagnostics_proposal.rst
@@ -34,10 +34,11 @@ cause of such failures. To do so, he must check if his OpenStack configuration
 is sane and consistent. These checks could be thought of as rules of diagnostic
 system.
 
-Currently OpenStack ecosystem lacks projects aimed to increase reliability and
-resilience of the cloud. With this proposal we want to introduce a project which
-will help operators to diagnose their OpenStack platform, reduce response time
-to known and unknown failures and effectively support the desired SLA.
+There are not many projects in OpenStack ecosystem aimed to increase reliability
+and resilience of the cloud at the operation stage. With this proposal we want
+to introduce a project which will help operators to diagnose their OpenStack
+platform, reduce response time to known and unknown failures and effectively
+support the desired SLA.
 
 Mission
 -------
@@ -47,7 +48,7 @@ minimize time and effort needed to identify and fix errors in operations
 maintenance phase of cloud life cycle.**
 
 User Stories
-------------
+-----------
 
 - As a **cloud operator**, I want to make sure that my OpenStack architecture
   and configuration is sane and consistent across all platform components and
diff --git a/doc/source/rules_engine.rst b/doc/source/rules_engine.rst
index 1fef778..80cce00 100644
--- a/doc/source/rules_engine.rst
+++ b/doc/source/rules_engine.rst
@@ -1,7 +1,7 @@
 Production Rules Engine
 =======================
 
-This document describes rules engine used for inspection and diagnostics of
+This document describes rule engine used for inspection and diagnostics of
 OpenStack configuration.
 
 Summary