Merge pull request #10163 from maxamillion/docs_yaml_dict_playbook

Add intro to playbook docs using YAML dictionaries

docsite/rst/playbooks_intro.rst

@@ -73,6 +73,43 @@ For starters, here's a playbook that contains just one play::
         - name: restart apache
           service: name=httpd state=restarted
 
+We can also break task items out over multiple lines using the YAML dictionary
+types to supply module arguments. This can be helpful when working with tasks
+that have really long parameters or modules that take many parameters to keep
+them well structured. Below is another version of the above example but using
+YAML dictionaries to supply the modules with their key=value arguments.::
+
+    ---
+    - hosts: webservers
+      vars:
+        http_port: 80
+        max_clients: 200
+      remote_user: root
+      tasks:
+      - name: ensure apache is at the latest version
+        yum:
+          pkg: httpd
+          state: latest
+      - name: write the apache config file
+        template:
+          src: /srv/httpd.j2
+          dest: /etc/httpd.conf
+        notify:
+        - restart apache
+      - name: ensure apache is running
+        service:
+          name: httpd
+          state: started
+      handlers:
+        - name: restart apache
+          service:
+            name: httpd
+            state: restarted
+
+.. note::
+
+    The above example using YAML dictionaries for module arguments can also be accomplished using the YAML multiline string syntax with the `>` character but this can lead to string quoting errors.
+
 Below, we'll break down what the various features of the playbook language are.
 
 .. _playbook_basics: