[doc] Improve documentation

Cleanup rules engine document
Include all documents in the proposal document

doc/openstack_architecture_model.rst

@@ -1,5 +1,4 @@
-=======================
+Architecture Data Model
-ARCHITECTURE DATA MODEL
 =======================
 
 Overview

doc/openstack_diagnostics_proposal.rst

@@ -1,15 +1,18 @@
+==============================
 OPENSTACK DIAGNOSTICS PROPOSAL
 ==============================
 
+.. contents::
+
 Project Name
-------------
+============
 
 **Official:** OpenStack Diagnostics
 
 **Codename:** Rubick
 
-Overview
+OVERVIEW
---------
+========
 
 The typical OpenStack cloud life cycle consists of 2 phases:
 
@@ -90,5 +93,13 @@ TripleO Heat and configuration files templates).
 Dependencies
 ------------
 
-Design
+DESIGN
-------
+======
+
+.. include:: service_architecture.rst
+
+.. include:: rules_engine.rst
+
+.. include:: openstack_integration.rst
+
+.. include:: openstack_architecture_model.rst

doc/openstack_integration.rst

@@ -1,5 +1,5 @@
-DIAGNOSTICS INTEGRATION WITH OPENSTACK
+Integration with OpenStack
-======================================
+==========================
 
 -------------------------------------
 Integration with OpenStack Deployment

doc/rules_engine.rst

@@ -1,32 +1,11 @@
-PRODUCTION RULES ENGINE
+Production Rules Engine
 =======================
 
 This document describes rules engine used for inspection and diagnostics of
 OpenStack configuration.
 
-----------------
+Summary
-Proposal Summary
+-------
-----------------
-
-With this proposal we want to introduce a project aimed to enhance and simplify
-operatinal maintenance of OpenStack cloud. Project provides service which uses
-rule-based engine to inspect configurations of OpenStack
-platform and find all kinds of architecture- and configuration-level glitches
-and inconsistencies.
-
-*# describe motivation behind rules
-# describe rules reuse
-# desribe rule-based inspection
-# example rule
-# mandatory rules vs. best-practice rules*
-
-This engine will provide hints and best practices to increase reliability and
-operational resilience of the cloud.
-
-#FIXME: move this part to document rules_engine.rst
-
-Rules-based approach to diagnostics
------------------------------------
 
 The consistent configuration across all components is essential to OpenStack
 cloud operation. If something is wrong with configuration, you as an operator
@@ -40,8 +19,20 @@ rules to be operational. On the other hand, if you know rules which your
 configuration breaks, you can identify incorrect parameters reliably and easy.
 That is how production rules or diagnostic systems work.
 
+Example production rule
+-----------------------
+
 Example production rule for OpenStack system could be::
 
-  if (condition)parameter) is (value) then (check_parameter_1) must be (value) and
+  Given (condition_parameter_1) is (value) and
-      (check_parameter_2) must be (value)
+  (condition_parameter_2) is (value)
+  then (check_parameter_1) must be (value)
 
+Rule-based inspection
+---------------------
+
+Store and reuse rules
+---------------------
+
+Sanity checks vs best practices
+-------------------------------

doc/service_architecture.rst

@@ -1,5 +1,11 @@
-===================
+Design & Architecture
-RUBICK ARCHITECTURE
 ===================
 
+This section describes design and architecture of OpenStack Diagnostics (Rubik)
+service.
+
+Service includes the following components:
+
+* 
+
 .. image:: images/service_architecture.png