Rewrote the precedence docs.

docsite/latest/rst/playbooks2.rst

@@ -857,30 +857,31 @@ Also see the module documentation section.
 Understanding Variable Precedence
 `````````````````````````````````
 
-You have already learned about inventory host and group variables, 'vars', and 'vars_files'.
+You have already learned about inventory variables, 'vars', and 'vars_files'.  In the
-
+event the same variable name occurs in more than one place, what happens?  There are really three tiers
-If a variable name is defined in more than one place with the same name, priority is as follows
+of precedence, and within those tiers, some minor ordering rules that you probably won't even need to remember.
-to determine which place sets the value of the variable.  Lower numbered items have the highest
+We'll explain them anyway though.
-priority.
+
-
+Variables that are set during the execution of the play have highest priority. This includes registered 
-1.  Any variables specified with --extra-vars (-e) on the ansible-playbook command line.
+variables and facts, which are discovered pieces of information about remote hosts.  
-
+
-2.  Variables loaded from YAML files mentioned in 'vars_files' in a playbook.
+Descending in priority are variables defined in the playbook.  'vars_files' as defined in the playbook are next up,
-
+followed by variables as passed to ansible-playbook via --extra-vars (-e), then variables defined in the 'vars' section.  These
-3.  facts, whether built in or custom, or variables assigned from the 'register' keyword.
+should all be taken to be basically the same thing -- good places to define constants about what the play does to all hosts
-
+in the play. 
-4.  variables passed to parameterized task include statements.
+
-
+Finally, inventory variables have the least priority.  Variables about hosts override those about groups.
-5.  'vars' as defined in the playbook.
+If a variable is defined in multiple groups and one group is a child of the other, the child group variable 
-
+will override the variable set in the parent.  
-6.  Host variables from inventory.
+
-
+This makes the 'group_vars/all' file the best place to define a default value you wish to override in another
-7.  Group variables from inventory in inheritance order.  This means if a group includes a sub-group, the variables
+group, or even in a playbook.  For example, your organization might set a default ntp server in group_vars/all
-    in the subgroup have higher precedence.
+and then override it based on a group based on a geographic region.  However if you type 'ntpserver: asdf.example.com'
-
+in a vars section of a playbook, you know from reading the playbook that THAT specific value is definitely the one
-Therefore, if you want to set a default value for something you wish to override somewhere else, the best
+that is going to be used.  You won't be fooled by some variable from inventory sneaking up on you.
-place to set such a default is in a group variable.  The 'group_vars/all' file makes an excellent place to put global
+
-variables that are true across your entire site, since everything has higher priority than these values.
+So, in short, if you want something easy to remember: facts beat playbook definitions, and 
+playbook definitions beat inventory variables.  
 
 
 Check Mode ("Dry Run") --check