Few changes in the doc

* Article "Architecture" is too small. It makes sense to add more
  information. - Added some more information

* I think we need to change "How to write an Action Plugin" to just
  "How to write a custom action". I think the word "plugin" here is
  not important from user perspective - Done

* I think we need to change "How to extend YAQL with a new function"
  to "How to write a custom YAQL function" and put it right next to
  "How to write a custom action". That would be more consistent.
  - Done

Change-Id: I9b43694072cb23271e33440741204da3e10b89ac
Partial-Implements: blueprint mistral-doc

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
+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 - stores workflow definitions, current execution states, and
+
+Persistence
+-----------
+
+The persistence stores workflow definitions, current execution states, and
 past execution results.

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
 

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

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