Update the user-guide to explain the main steps

Added a new sequence diagram to explain showing the main steps
regarding Watcher usage:
- create a new audit template
- launch an audit and receive a recommended action plan
- launch the action plan

Change-Id: I1a0031b957d34908020be06870ed1d2772cd5af6
Closes-Bug: 1536731

doc/source/deploy/user-guide.rst

@@ -10,11 +10,20 @@
 Welcome to the Watcher User Guide
 =================================
 
-In the `architecture <https://wiki.openstack.org/wiki/WatcherArchitecture>`_
+See the
-you got information about how it works.
+`architecture page <https://factory.b-com.com/www/watcher/doc/watcher/architecture.html>`_
+for an architectural overview of the different components of Watcher and how
+they fit together.
+
 In this guide we're going to take you through the fundamentals of using
 Watcher.
 
+The following diagram shows the main interactions between the
+:ref:`Administrator <administrator_definition>` and the Watcher system:
+
+.. image:: ../images/sequence_overview_watcher_usage.png
+   :width: 100%
+
 
 Getting started with Watcher
 ----------------------------
@@ -119,3 +128,4 @@ You can also obtain more detailed information about a specific action:
 .. code:: bash
 
   $ watcher action-show <the_action_uuid>
+

doc/source/image_src/plantuml/sequence_overview_watcher_usage.txt

@@ -0,0 +1,37 @@
+@startuml
+
+actor Administrator
+
+== Create some Audit settings ==
+
+Administrator -> Watcher : create new Audit Template (i.e. Audit settings : goal, scope, deadline,...)
+Watcher -> Watcher : save Audit Template in database
+Administrator <-- Watcher : Audit Template UUID
+
+== Launch a new Audit ==
+
+Administrator -> Watcher : launch new Audit of the Openstack infrastructure resources\nwith a previously created Audit Template
+Administrator <-- Watcher : Audit UUID
+Administrator -> Watcher : get the Audit state
+Administrator <-- Watcher : ONGOING
+Watcher -> Watcher : compute a solution to achieve optimization goal
+Administrator -> Watcher : get the Audit state
+Administrator <-- Watcher : SUCCEEDED
+
+== Get the result of the Audit ==
+
+Administrator -> Watcher : get Action Plan
+Administrator <-- Watcher : recommended Action Plan and estimated efficacy
+Administrator -> Administrator : verify the recommended actions\nand evaluate the estimated gain vs aggressiveness of the solution
+
+== Launch the recommended Action Plan ==
+
+Administrator -> Watcher : launch the Action Plan
+Administrator <-- Watcher : Action Plan has been launched
+Watcher -> Watcher : trigger Actions on Openstack services
+Administrator -> Watcher : get the Action Plan state
+Administrator <-- Watcher : ONGOING
+Administrator -> Watcher : get the Action Plan state
+Administrator <-- Watcher : SUCCEEDED
+
+@enduml