updated yaml syntax and gotchas

specifically added example for getting strings that match boolean values

1 files changed, 31 insertions, 24 deletions

diff --git a/docsite/rst/YAMLSyntax.rst b/docsite/rst/YAMLSyntax.rst
index 76683f6ba3..ea3593d6fd 100644
--- a/docsite/rst/YAMLSyntax.rst
+++ b/docsite/rst/YAMLSyntax.rst
@@ -20,52 +20,52 @@ Each item in the list is a list of key/value pairs, commonly
 called a "hash" or a "dictionary".  So, we need to know how
 to write lists and dictionaries in YAML.
 
-There's another small quirk to YAML.  All YAML files (regardless of their association with
-Ansible or not) should begin with ``---``.  This is part of the YAML
-format and indicates the start of a document.
+There's another small quirk to YAML.  All YAML files (regardless of their association with Ansible or not) can optionally
+begin with ``---`` and end with ``...``.  This is part of the YAML format and indicates the start and end of a document.
 
-All members of a list are lines beginning at the same indentation level starting
-with a ``"- "`` (a dash and a space)::
+All members of a list are lines beginning at the same indentation level starting with a ``"- "`` (a dash and a space)::
 
     ---
     # A list of tasty fruits
-    - Apple
-    - Orange
-    - Strawberry
-    - Mango
+    fruits:
+        - Apple
+        - Orange
+        - Strawberry
+        - Mango
+    ...
 
 A dictionary is represented in a simple ``key: value`` form (the colon must be followed by a space)::
 
-    ---
     # An employee record
-    name: Example Developer
-    job: Developer
-    skill: Elite
+    -  martin:
+        name: Martin D'vloper
+        job: Developer
+        skill: Elite
 
-Dictionaries can also be represented in an abbreviated form if you really want to::
+Dictionaries and lists can also be represented in an abbreviated form if you really want to::
 
     ---
-    # An employee record
-    {name: Example Developer, job: Developer, skill: Elite}
+    employees:
+      -  martin: {name: Martin D'vloper, job: Developer, skill: Elite}
+    fruits: ['Apple', 'Orange', 'Strawberry', 'Mango]
 
 .. _truthiness:
 
-Ansible doesn't really use these too much, but you can also specify a 
-boolean value (true/false) in several forms::
+Ansible doesn't really use these too much, but you can also specify a boolean value (true/false) in several forms::
 
-    ---
     create_key: yes
     needs_agent: no
     knows_oop: True
     likes_emacs: TRUE
     uses_cvs: false
 
-Let's combine what we learned so far in an arbitrary YAML example.  This really
-has nothing to do with Ansible, but will give you a feel for the format::
+
+Let's combine what we learned so far in an arbitrary YAML example.
+This really has nothing to do with Ansible, but will give you a feel for the format::
 
     ---
     # An employee record
-    name: Example Developer
+    name: Martin D'vloper
     job: Developer
     skill: Elite
     employed: True
@@ -79,8 +79,7 @@ has nothing to do with Ansible, but will give you a feel for the format::
         python: Elite
         dotnet: Lame
 
-That's all you really need to know about YAML to start writing
-`Ansible` playbooks.
+That's all you really need to know about YAML to start writing `Ansible` playbooks.
 
 Gotchas
 -------
@@ -100,6 +99,14 @@ with a "{", YAML will think it is a dictionary, so you must quote it, like so::
 
     foo: "{{ variable }}"
 
+The same applies for strings that start or contain any YAML special characters `` [] {} : > | `` .
+
+Boolean conversion is helpful, but this can be a problem when you want a literal `yes` or other boolean values as a string.
+In these cases just use quotes::
+
+    non_boolean: "yes"
+    other_string: "False"
+
 
 .. seealso::