Move terminology definition to class related

As of now, the glossary defined in our documentation reflects the
current state of the codebase. In order to avoid any discrepancy
between the codebase and each definition, the objective here is to
gather both in a single place and link it into the rst documentation
via a custom directive.
Also re-aligned the requirements with liberty for doc.

Change-Id: I3089fd9f948b948115672f10937b1500b96ce180
Partial-Bug: #1526671

watcher/decision_engine/planner/base.py

@@ -16,6 +16,30 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 #
+
+"""
+The :ref:`Watcher Planner <watcher_planner_definition>` is part of the
+:ref:`Watcher Decision Engine <watcher_decision_engine_definition>`.
+
+This module takes the set of :ref:`Actions <action_definition>` generated by a
+:ref:`Strategy <strategy_definition>` and builds the design of a workflow which
+defines how-to schedule in time those different
+:ref:`Actions <action_definition>` and for each
+:ref:`Action <action_definition>` what are the prerequisite conditions.
+
+It is important to schedule :ref:`Actions <action_definition>` in time in order
+to prevent overload of the :ref:`Cluster <cluster_definition>` while applying
+the :ref:`Action Plan <action_plan_definition>`. For example, it is important
+not to migrate too many instances at the same time in order to avoid a network
+congestion which may decrease the :ref:`SLA <sla_definition>` for
+:ref:`Customers <customer_definition>`.
+
+It is also important to schedule :ref:`Actions <action_definition>` in order to
+avoid security issues such as denial of service on core OpenStack services.
+
+See :doc:`architecture` for more details on this component.
+"""
+
 import abc
 import six