Update the documentation

Update the docs to include some of the best practice concepts expected
for this repo.

Change-Id: I92a01e3154f6f7fadc9870ae47c6dc6221ba0e81

README.md

@@ -1,4 +1,9 @@
 tripleo-operator-ansible
 ========================
 
-This repository contains an ansible collection of TripleO roles.
+This repository contains an ansible collection of TripleO roles. This collection
+contains a set of roles providing an ansible interface for the TripleO cli actions.
+
+Documentation
+-------------
+Documentation can be viewed at https://docs.openstack.org/tripleo-operator-ansible/latest/

doc/source/bestpractices.rst

@@ -0,0 +1,43 @@
+==============
+Best Practices
+==============
+
+
+The roles provided in this collection wrap the tripleoclient actions that are
+used to deploy and manage an undercloud and overcloud. The point of these
+roles is to establish a common interface for Ansible based automation.
+
+
+Ansible Collection Namespace
+----------------------------
+
+tripleo-operator-ansible is an Ansible collection. In order to consume the
+roles and plugins within this repository, it needs to be installed as a
+collection.  This repository provides the `tripleo.operator` namespace.
+When writing playbooks, the usage of the `collections:` keyword
+is required in order for them to be executed. See the `Ansible Collection Documentation`_
+for additional details.
+
+.. _Ansible Collection Documentation: https://docs.ansible.com/ansible/latest/user_guide/collections_using.html#using-collections-in-a-playbook
+
+
+Role Naming Convention
+----------------------
+
+To general naming scheme for the roles provide is to take the openstackclient
+command and replace `openstack` with `tripleo` and use underscores instead
+of spaces. For example, `openstack overcloud deploy` becomes
+`tripleo_overcloud_deploy`. The exception to this rule is when the command
+itself start with `openstack tripleo`. Rather than double the `tripleo` in the
+role name, we only specify it once. For example `openstack tripleo container image prepare`
+is simply `tripleo_container_image_prepare`.
+
+
+Variable Naming Convention
+--------------------------
+
+The variables used by each role are prefixed with the role name. For example
+all roles contain a debug variable that can be used to print out the data used
+when executing the specific commands. For example, `tripleo_overcloud_deploy_debug`
+can be used to print out the cli command and the environment data used when
+the command is executed.

doc/source/index.rst

@@ -7,8 +7,9 @@ Contents:
    :maxdepth: 2
 
    installation
-   contributing
    usage
+   bestpractices
+   contributing
    roles
 
 Indices and tables