diff --git a/doc/source/roles/role-overcloud_service_status.rst b/doc/source/roles/role-overcloud_service_status.rst
index 4ab8d6cce..8e8548e0c 100644
--- a/doc/source/roles/role-overcloud_service_status.rst
+++ b/doc/source/roles/role-overcloud_service_status.rst
@@ -2,6 +2,47 @@
 overcloud_service_status
 ========================
 
+--------------
+About The Role
+--------------
+
+An Ansible role to verify the ``Overcloud`` services states after a deployment
+or an update. It checks the ``API /os-services`` and looks for deprecated
+services (``nova-consoleauth``) or any down services.
+
+Requirements
+============
+
+This role needs to be run on an ``Undercloud`` with a deployed ``Overcloud``.
+
+Dependencies
+============
+
+No dependencies.
+
+Example Playbook
+================
+
+.. code-block:: yaml
+
+   - hosts: undercloud
+     roles:
+       - { role: overcloud_service_status }
+
+License
+=======
+
+Apache
+
+Author Information
+==================
+
+**Red Hat TripleO DFG:Compute Squad:Deployment**
+
+----------------
+Full Description
+----------------
+
 .. ansibleautoplugin::
    :role: roles/overcloud_service_status
 
diff --git a/roles/overcloud_service_status/README.md b/roles/overcloud_service_status/README.md
deleted file mode 100644
index 342bed99e..000000000
--- a/roles/overcloud_service_status/README.md
+++ /dev/null
@@ -1,47 +0,0 @@
-Overcloud-service-status
-=========================
-
-An Ansible role to verify the Overcloud services states after a deployment or an update.
-It checks the API /os-services and looks for deprecated services (nova-consoleauth) or
-any down services.
-
-Requirements
-------------
-
-This role needs to be run on an Undercloud with a deployed Overcloud.
-
-Role Variables
---------------
-
-- overcloud_service_status_debug: Wether or not to log the token request
-- overcloud_deprecated_services: A list of services that shouldn't be registered any more
-- overcloud_service_api: overcloud API to validate against
-
-These variables are normally set as host variables for the undercloud when generating
-the inventory with tripleo-ansible-inventory:
-- overcloud_keystone_url
-- overcloud_admin_password
-
-
-Dependencies
-------------
-
-No dependencies.
-
-Example Playbook
-----------------
-
-
-    - hosts: undercloud
-      roles:
-         - { role: overcloud_service_status }
-
-License
--------
-
-Apache
-
-Author Information
-------------------
-
-Red Hat Nova Deployment Squad Team.
diff --git a/roles/overcloud_service_status/defaults/main.yml b/roles/overcloud_service_status/defaults/main.yml
index f83fc07b2..0896d0ec0 100644
--- a/roles/overcloud_service_status/defaults/main.yml
+++ b/roles/overcloud_service_status/defaults/main.yml
@@ -18,10 +18,21 @@
 # All variables intended for modification should place placed in this file.
 
 # All variables within this role should have a prefix of "overcloud_service_status"
+
+# Debugging mode, whether or no to log the token request
 overcloud_service_status_debug: false
+
+# Overcloud API to validate against
 overcloud_service_api:
   - nova
   - cinderv3
+
+# A list of services that shouldn't be registered any more
 overcloud_deprecated_services:
   nova:
     - nova-consoleauth
+
+# These variables are normally set as host variables for the undercloud when generating
+# the inventory with tripleo-ansible-inventory:
+# - overcloud_keystone_url
+# - overcloud_admin_password