Updates and fixes to the user guide

Change-Id: I42198bbdf4f9e6f6f337761b6ff6900c4bb7f171
Signed-off-by: jose.lausuch <jose.lausuch@ericsson.com>
(cherry picked from commit 94dbd87d341ed72beb975b4b7b76135ea52d3b17)

1 files changed, 31 insertions, 30 deletions

diff --git a/docs/userguide/troubleshooting.rst b/docs/userguide/troubleshooting.rst
index ac96bb930..d2145659c 100644
--- a/docs/userguide/troubleshooting.rst
+++ b/docs/userguide/troubleshooting.rst
@@ -7,8 +7,8 @@ Troubleshooting
 This section gives some guidelines about how to troubleshoot the test cases
 owned by Functest.
 
-**IMPORTANT**: The steps defined below must be executed inside the Functest Docker
-container and after sourcing the OpenStack credentials::
+**IMPORTANT**: As in the previous section, the steps defined below must be
+executed inside the Functest Docker container and after sourcing the OpenStack credentials::
 
     . $creds
 
@@ -23,28 +23,30 @@ This section covers the test cases related to the VIM (vPing, Tempest, Rally).
 
 vPing common
 ^^^^^^^^^^^^
-For both vPing test cases (vPing_SSH, and vPing_userdata), the first steps are
+For both vPing test cases (**vPing_ssh**, and **vPing_userdata**), the first steps are
 similar:
-* Create Glance image
-* Create Network
-* Create Security Group
-* Create instances
 
-After these actions, the test cases differ and will be explained in their section.
+    * Create Glance image
+    * Create Network
+    * Create Security Group
+    * Create instances
 
-This test cases can be run inside the container as follows::
+After these actions, the test cases differ and will be explained in their respective section.
+
+These test cases can be run inside the container as follows::
 
     $repos_dir/functest/docker/run_tests.sh -t vping_ssh
     $repos_dir/functest/docker/run_tests.sh -t vping_userdata
 
-The *run_tests.sh* script is calling internally the vPing scripts, located in
-*$repos_dir/functest/testcases/vPing/CI/libraries/vPing_ssh.py* or
+The **run_tests.sh** script is basically calling internally the corresponding
+vPing scripts, located in
+*$repos_dir/functest/testcases/vPing/CI/libraries/vPing_ssh.py* and
 *$repos_dir/functest/testcases/vPing/CI/libraries/vPing_userdata.py* with the
 appropriate flags.
 
 After finishing the test execution, the corresponding script will remove all
 created resources in OpenStack (image, instances, network and security group).
-When troubleshooting, it is handy sometimes to keep those resources in case the
+When troubleshooting, it is advisable sometimes to keep those resources in case the
 test fails and a manual testing is needed. This can be achieved by adding the flag *-n*::
 
     $repos_dir/functest/docker/run_tests.sh -n -t vping_ssh
@@ -78,8 +80,8 @@ In this case, proceed to create it manually. These are some hints::
     neutron security-group-rule-create sg-test --direction egress --ethertype IPv4 --protocol tcp --port-range-min 80 --port-range-max 80 --remote-ip-prefix 0.0.0.0/0
 
 The next step is to create the instances. The image used is located in
-*/home/opnfv/functest/data/cirros-0.3.4-x86_64-disk.img* and a glance image is created
-with the name *functest-vping*. If booting the instances fails (i.e. the status
+*/home/opnfv/functest/data/cirros-0.3.4-x86_64-disk.img* and a Glance image is created
+with the name **functest-vping**. If booting the instances fails (i.e. the status
 is not **ACTIVE**), you can check why it failed by doing::
 
     nova list
@@ -87,11 +89,9 @@ is not **ACTIVE**), you can check why it failed by doing::
 
 It might show some messages about the booting failure. To try that manually::
 
-    net_id=$(neutron net-list | grep net-test | awk '{print $2}')
-    nova boot --flavor 2 --image functest-vping --nic net-id=$net_id nova-test
+    nova boot --flavor 2 --image functest-vping --nic net-id=<NET_ID> nova-test
 
-This will spawn a VM using the network created previously manually. If you want to use
-the existing vPing network, just replace *net-test* by *vping-net*.
+This will spawn a VM using the network created previously manually.
 In all the OPNFV tested scenarios from CI, it never has been a problem with the
 previous actions. Further possible problems are explained in the following sections.
 
@@ -99,8 +99,8 @@ previous actions. Further possible problems are explained in the following secti
 vPing_SSH
 ^^^^^^^^^
 This test case creates a floating IP on the external network and assigns it to
-the second instance with name *opnfv-vping-2*. The purpose of this is to establish
-a SSH connection to that instance to SCP a script that will ping the first insntace.
+the second instance **opnfv-vping-2**. The purpose of this is to establish
+a SSH connection to that instance and SCP a script that will ping the first instance.
 This script is located in the repository under
 *$repos_dir/functest/testcases/vPing/CI/libraries/ping.sh* and takes an IP as
 a parameter. When the SCP is completed, the test will do an SSH call to that script
@@ -109,13 +109,13 @@ inside the second instance. Some problems can happen here::
     vPing_ssh- ERROR - Cannot establish connection to IP xxx.xxx.xxx.xxx. Aborting
 
 If this is displayed, stop the test or wait for it to finish (if you have used the flag
-*-n* in *run_tests.sh* explained previously) so that the test does not clean
+*-n* in **run_tests.sh** explained previously) so that the test does not clean
 the OpenStack resources. It means that the Container can not reach the public
-IP assigned to the instance *opnfv-vping-2*. There are many possible reasons, and
+IP assigned to the instance **opnfv-vping-2**. There are many possible reasons, and
 they really depend on the chosen scenario. For most of the ODL-L3 and ONOS scenarios
 this has been noticed and it is a known limitation.
 
-First, make sure that the instance *opnfv-vping-2* managed to get an IP from
+First, make sure that the instance **opnfv-vping-2** succeeded to get an IP from
 the DHCP agent. It can be checked by doing::
 
     nova console-log opnfv-vping-2
@@ -142,7 +142,8 @@ manually with the steps described above in the vPing common section with the add
 
 
 Further troubleshooting is out of scope of this document, as it might be due to
-problems with the SDN controller. Contact the installer team members.
+problems with the SDN controller. Contact the installer team members or send an
+email to the corresponding OPNFV mailing list for more information.
 
 
 
@@ -151,14 +152,14 @@ vPing_userdata
 This test case does not create any floating IP neither establishes an SSH
 connection. Instead, it uses nova-metadata service when creating an instance
 to pass the same script as before (ping.sh) but as 1-line text. This script
-will be executed automatically when the second instance *opnfv-vping-2* is booted.
+will be executed automatically when the second instance **opnfv-vping-2** is booted.
 
 The only known problem here for this test to fail is mainly the lack of support
 of cloud-init (nova-metadata service). Check the console of the instance::
 
     nova console-log opnfv-vping-2
 
-If this text or similar is showed::
+If this text or similar is shown::
 
     checking http://169.254.169.254/2009-04-04/instance-id
     failed 1/20: up 1.13. request failed
@@ -184,9 +185,9 @@ If this text or similar is showed::
     failed to read iid from metadata. tried 20
 
 it means that the instance failed to read from the metadata service. Contact
-the installer team members for more information.
+the Functest or installer teams for more information.
 
-Cloud-init in not supported on scenario dealing with ONOS and the tests have been
+NOTE: Cloud-init in not supported on scenario dealing with ONOS and the tests have been
 excluded from CI in those scenarios.
 
 
@@ -297,7 +298,7 @@ due to wrong return code.
 ONOS
 ^^^^
 
-TODO
+Please refer to the ONOS documentation.
 
 OpenContrail
 ^^^^^^^^^^^^
@@ -338,4 +339,4 @@ described in the following table:
 Promise
 ^^^^^^^
 
-TODO
+Please refer to the Promise documentation.