3 files changed, 95 insertions, 3 deletions
diff --git a/docs/best_practices_guide.adoc b/docs/best_practices_guide.adoc
index 841f6e72c..9208e99a3 100644
--- a/docs/best_practices_guide.adoc
+++ b/docs/best_practices_guide.adoc
@@ -1,6 +1,6 @@
 // vim: ft=asciidoc
 
-= Openshift-Ansible Best Practices Guide
+= openshift-ansible Best Practices Guide
 
 The purpose of this guide is to describe the preferred patterns and best practices used in this repository (both in ansible and python).
 
@@ -27,6 +27,32 @@ The tooling is flexible enough that exceptions can be made so that the tool the
 
 == Python
 
+=== Method Signatures
+
+'''
+[cols="2v,v"]
+|===
+| **Rule**
+| When adding a new paramemter to an existing method, a default value SHOULD be used
+|===
+The purpose of this rule is to make it so that method signatures are backwards compatible.
+
+If this rule isn't followed, it will be necessary for the person who changed the method to search out all callers and make sure that they're able to use the new method signature.
+
+Example:
+.Before:
+[source,python]
+----
+def add_person(first_name, last_name):
+----
+
+.After:
+[source,python]
+----
+def add_person(first_name, last_name, age=None):
+----
+
+
 === PyLint
 http://www.pylint.org/[PyLint] is used in an attempt to keep the python code as clean and as managable as possible. The build bot runs each pull request through PyLint and any warnings or errors cause the build bot to fail the pull request.
 
@@ -99,6 +125,58 @@ YAML is a superset of JSON, which means that Ansible allows JSON syntax to be in
 
 Every effort should be made to keep our Ansible YAML files in pure YAML.
 
+'''
+[cols="2v,v"]
+|===
+| **Rule**
+| Parameters to Ansible Modules SHOULD use the Yaml dictionary format when 3 or more parameters are being passed
+|===
+
+When a module has several parameters that are being passed in, it's hard to see exactly what value each parameter is getting. It is preferred to use the Ansible Yaml syntax to pass in parameters so that it's more clear what values are being passed for each paramemter.
+
+.Bad:
+[source,yaml]
+----
+- file: src=/file/to/link/to dest=/path/to/symlink owner=foo group=foo state=link
+----
+
+.Good:
+[source,yaml]
+----
+- file:
+    src: /file/to/link/to
+    dest: /path/to/symlink
+    owner: foo
+    group: foo
+    state: link
+----
+
+
+'''
+[cols="2v,v"]
+|===
+| **Rule**
+| Parameters to Ansible Modules SHOULD use the Yaml dictionary format when the line length exceeds 120 characters
+|===
+
+Lines that are long quickly become a wall of text that isn't easily parsable. It is preferred to use the Ansible Yaml syntax to pass in parameters so that it's more clear what values are being passed for each paramemter.
+
+.Bad:
+[source,yaml]
+----
+- get_url: url=http://example.com/path/file.conf dest=/etc/foo.conf sha256sum=b5bb9d8014a0f9b1d61e21e796d78dccdf1352f23cd32812f4850b878ae4944c
+----
+
+.Good:
+[source,yaml]
+----
+- get_url:
+    url: http://example.com/path/file.conf
+    dest: /etc/foo.conf
+    sha256sum: b5bb9d8014a0f9b1d61e21e796d78dccdf1352f23cd32812f4850b878ae4944c
+----
+
+
 === Defensive Programming
 
 .Context
diff --git a/docs/core_concepts_guide.adoc b/docs/core_concepts_guide.adoc
index 38187c55e..b29e467e2 100644
--- a/docs/core_concepts_guide.adoc
+++ b/docs/core_concepts_guide.adoc
@@ -1,6 +1,6 @@
 // vim: ft=asciidoc
 
-= Openshift-Ansible Core Concepts Guide
+= openshift-ansible Core Concepts Guide
 
 The purpose of this guide is to describe core concepts used in this repository.
 
diff --git a/docs/style_guide.adoc b/docs/style_guide.adoc
index 3b888db12..2f89a5fae 100644
--- a/docs/style_guide.adoc
+++ b/docs/style_guide.adoc
@@ -1,6 +1,6 @@
 // vim: ft=asciidoc
 
-= Openshift-Ansible Style Guide
+= openshift-ansible Style Guide
 
 The purpose of this guide is to describe the preferred coding conventions used in this repository (both in ansible and python).
 
@@ -43,6 +43,20 @@ This is a hard limit and is enforced by the build bot. This check MUST NOT be di
 
 == Ansible
 
+
+=== Ansible Yaml file extension
+'''
+[cols="2v,v"]
+|===
+| **Rule**
+| All Ansible Yaml files MUST have a .yml extension (and NOT .YML, .yaml etc).
+|===
+
+Ansible tooling (like `ansible-galaxy init`) create files with a .yml extension. Also, the Ansible documentation website references files with a .yml extension several times. Because of this, it is normal in the Ansible community to use a .yml extension for all Ansible Yaml files.
+
+Example: `tasks.yml`
+
+
 === Ansible Global Variables
 Ansible global variables are defined as any variables outside of ansible roles. Examples include playbook variables, variables passed in on the cli, etc.