From 70b2ceebe52e796c0ecffad2ab44397c034ea3a5 Mon Sep 17 00:00:00 2001
From: Brian Coca <brian.coca+git@gmail.com>
Date: Tue, 23 May 2017 10:55:59 -0400
Subject: [PATCH] document new 'order' keyword for plays

---
 docs/docsite/rst/playbooks_intro.rst | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/docs/docsite/rst/playbooks_intro.rst b/docs/docsite/rst/playbooks_intro.rst
index 3322fe3e47..edae29ca80 100644
--- a/docs/docsite/rst/playbooks_intro.rst
+++ b/docs/docsite/rst/playbooks_intro.rst
@@ -229,6 +229,31 @@ Just `Control-C` to kill it and run it again adding the appropriate password.
    not come into play. Ansible also takes care to not log password
    parameters.
 
+
+.. _version_added: 2.4
+.. _order:
+You can also control the order in which hosts are run, the default is to follow the order supplied by the inventory::
+
+    - hosts: all
+      order: sorted
+      gather_facts: False
+      tasks:
+        - debug: var=inventory_hostname
+
+Possible values for order are:
+
+inventory:
+    The default, the order is 'as provided' by the inventory
+reverse_inventory:
+    As the name implies, this reverses the order 'as provided' by the inventory
+sorted:
+    Hosts are albhabetically sorted by name
+reverse_sorted:
+    Reverse alphabetic ordered
+shuffle:
+    Hosts are randomly ordered each run
+
+
 .. _tasks_list:
 
 Tasks list