diff --git a/doc/source/architecture.rst b/doc/source/architecture.rst
index 8c6c76150..eb2664e04 100644
--- a/doc/source/architecture.rst
+++ b/doc/source/architecture.rst
@@ -1,16 +1,65 @@
-Architecture
-============
+Mistral Architecture
+====================
+
+Mistral is OpenStack workflow service. The main aim of the project is to provide
+capability to define, execute and manage tasks and workflows without writing
+code.
+
+
+Basic concepts
+~~~~~~~~~~~~~~
+
+A few basic concepts that one has to understand before going through the Mistral
+architecture are given below:
+
+* Workflow - consists of tasks (at least one) describing what exact steps should
+  be made during workflow execution.
+* Task - an activity executed within the workflow definition.
+* Action - work done when an exact task is triggered.
+
+Mistral components
+~~~~~~~~~~~~~~~~~~
+
+Mistral is composed of the following major components:
+
+* API Server
+* Engine
+* Task Executors
+* Scheduler
+* Persistence
+
+The following diagram illustrates the architecture of mistral:
 
 .. image:: img/mistral_architecture.png
 
-* Engine - handles control and data flow of workflow executions. Computes which
-  tasks are ready and places them in a queue. Passes the data from task to
-  task, deals with condition transitions, etc.
-* Task Executors - execute task Actions. Pick up tasks from the queue, run
-  actions, and send results back to the engine.
-* API server - exposes REST API to operate and monitor workflow executions.
-* Scheduler - stores and executes delayed calls. It is the important Mistral
-  component since it interacts with engine and executors. It also triggers
-  workflows on events (e.g., periodic cron event)
-* Persistence - stores workflow definitions, current execution states, and
-  past execution results.
+API server
+----------
+
+The API server exposes REST API to operate and monitor the workflow executions.
+
+Engine
+------
+
+The Engine picks up the workflows from the workflow queue. It handles the control
+and dataflow of workflow executions. It also computes which tasks are ready and
+places them in a task queue. It passes the data from task to task, deals with
+condition transitions, etc.
+
+Task Executors
+--------------
+
+The Task Executor executes task Actions. It picks up the tasks from the queue,
+run actions, and sends results back to the engine.
+
+Scheduler
+---------
+
+The scheduler stores and executes delayed calls. It is the important Mistral
+component since it interacts with engine and executors. It also triggers
+workflows on events (e.g., periodic cron event)
+
+Persistence
+-----------
+
+The persistence stores workflow definitions, current execution states, and
+past execution results.
diff --git a/doc/source/developer/creating_custom_action.rst b/doc/source/developer/creating_custom_action.rst
index 83afdb583..49d5eb1b2 100644
--- a/doc/source/developer/creating_custom_action.rst
+++ b/doc/source/developer/creating_custom_action.rst
@@ -1,6 +1,6 @@
-=============================
-How to write an Action Plugin
-=============================
+============================
+How to write a Custom Action
+============================
 
 1. Write a class inherited from mistral.actions.base.Action
 
diff --git a/doc/source/developer/extending_yaql.rst b/doc/source/developer/extending_yaql.rst
index f4fc95af0..6a7e59b68 100644
--- a/doc/source/developer/extending_yaql.rst
+++ b/doc/source/developer/extending_yaql.rst
@@ -1,6 +1,6 @@
-======================================
-How to extend YAQL with a new function
-======================================
+===================================
+How to write a custom YAQL function
+===================================
 
 ********
 Tutorial
diff --git a/doc/source/developer/index.rst b/doc/source/developer/index.rst
index 956b96be0..27df73ff8 100644
--- a/doc/source/developer/index.rst
+++ b/doc/source/developer/index.rst
@@ -5,7 +5,7 @@ Developer's Reference
    :maxdepth: 3
 
    creating_custom_action
-   asynchronous_actions
    extending_yaql
+   asynchronous_actions
    devstack
    troubleshooting