Further docs hacking

docsite/rst/YAMLSyntax.rst

@@ -38,7 +38,7 @@ A dictionary is represented in a simple ``key:`` and ``value`` form::
 
     ---
     # An employee record
-    name: John Eckersberg
+    name: Example Developer
     job: Developer
     skill: Elite
 
@@ -46,7 +46,7 @@ Dictionaries can also be represented in an abbreviated form if you really want t
 
     ---
     # An employee record
-    {name: John Eckersberg, job: Developer, skill: Elite}
+    {name: Example Developer, job: Developer, skill: Elite}
 
 .. _truthiness:
 
@@ -63,7 +63,7 @@ has nothing to do with Ansible, but will give you a feel for the format::
 
     ---
     # An employee record
-    name: John Eckersberg
+    name: Example Developer
     job: Developer
     skill: Elite
     employed: True
@@ -80,6 +80,19 @@ has nothing to do with Ansible, but will give you a feel for the format::
 That's all you really need to know about YAML to get started writing
 `Ansible` playbooks.
 
+Gotchas
+-------
+
+While YAML is generally friendly, the following is going to be a YAML syntax error:
+
+    foo: somebody said I should put a colon here: so I did
+
+You will want to quote any hash values using colons, like so:
+
+    foo: "somebody said I should put a colon here: so I did"
+
+And then the colon will be preserved.
+
 .. seealso::
 
    :doc:`playbooks`

docsite/rst/playbooks2.rst

@@ -254,6 +254,16 @@ there will be accessible to future tasks::
           action: site_facts
         - action: command echo ${my_custom_fact_can_be_used_now}
 
+One common useful trick with only_if is to key off the changed result of a last command.  As an example::
+
+    tasks:
+        - action: template src=/templates/foo.j2 dest=/etc/foo.conf
+        - action: command echo 'the file has changed'
+          only_if: '${last_result.changed}'
+
+$last_result is a variable automatically set by Ansible, and it is a boolean, so there is no need
+to test for it against something else with an explicit equals.  This assumes Ansible 0.8 and later.
+
 In Ansible 0.8, a few shortcuts are available for testing whether a variable is defined or not::
 
     tasks: