Documentation on goal and efficacy

In this changeset, I wrote a documentation detailing how one can
implement a new goal plugin. I also mention to define the efficacy
specification for a given goal.

Partially Implements: blueprint efficacy-indicator

Change-Id: Iba267ae312f248b49d4600504f11678cdc225622

watcher/decision_engine/audit/default.py

@@ -13,6 +13,7 @@
 # implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
+
 from oslo_log import log
 
 from watcher.common.messaging.events import event as watcher_event

watcher/decision_engine/goal/efficacy/base.py

@@ -14,6 +14,15 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+An efficacy specfication is a contract that is associated to each :ref:`Goal
+<goal_definition>` that defines the various :ref:`efficacy indicators
+<efficacy_indicator_definition>` a strategy achieving the associated goal
+should provide within its :ref:`solution <solution_definition>`. Indeed, each
+solution proposed by a strategy will be validated against this contract before
+calculating its :ref:`global efficacy <efficacy_definition>`.
+"""
+
 import abc
 import json
 

watcher/decision_engine/solution/base.py

@@ -18,10 +18,17 @@
 #
 
 """
-A :ref:`Solution <solution_definition>` is a set of
-:ref:`Actions <action_definition>` generated by a
-:ref:`Strategy <strategy_definition>` (i.e., an algorithm) in order to achieve
-the :ref:`Goal <goal_definition>` of an :ref:`Audit <audit_definition>`.
+A :ref:`Solution <solution_definition>` is the result of execution of a
+:ref:`strategy <strategy_definition>` (i.e., an algorithm).
+Each solution is composed of many pieces of information:
+
+- A set of :ref:`actions <action_definition>` generated by the strategy in
+  order to achieve the :ref:`goal <goal_definition>` of an associated
+  :ref:`audit <audit_definition>`.
+- A set of :ref:`efficacy indicators <efficacy_indicator_definition>` as
+  defined by the associated goal
+- A :ref:`global efficacy <efficacy_definition>` which is computed by the
+  associated goal using the aforementioned efficacy indicators.
 
 A :ref:`Solution <solution_definition>` is different from an
 :ref:`Action Plan <action_plan_definition>` because it contains the