Merge pull request #15172 from charleswhchan/patch-1

Improve documentation.

docsite/rst/intro_adhoc.rst

@@ -166,10 +166,10 @@ Ensure a package is not installed::
 
     $ ansible webservers -m yum -a "name=acme state=absent"
 
-Ansible has modules for managing packages under many platforms.  If your package manager
-does not have a module available for it, you can install
-packages using the command module or (better!) contribute a module
-for other package managers.  Stop by the mailing list for info/details.
+Ansible has modules for managing packages under many platforms.  If there isn't 
+a module for your package manager, you can install packages using the 
+command module or (better!) contribute a module for your package manager. 
+Stop by the mailing list for info/details.
 
 .. _users_and_groups:
 
@@ -223,8 +223,10 @@ Ensure a service is stopped::
 Time Limited Background Operations
 ``````````````````````````````````
 
-Long running operations can be backgrounded, and their status can be checked on
-later. If you kick hosts and don't want to poll, it looks like this::
+Long running operations can be run in the background, and it is possible to
+check their status later. For example, to execute ``long_running_operation`
+asynchronously in the background, with a timeout of 3600 seconds (``-B``), 
+and without polling (-P)::
 
     $ ansible all -B 3600 -P 0 -a "/usr/bin/long_running_operation --do-stuff"
 
@@ -238,7 +240,7 @@ Polling is built-in and looks like this::
 
     $ ansible all -B 1800 -P 60 -a "/usr/bin/long_running_operation --do-stuff"
 
-The above example says "run for 30 minutes max (``-B``: 30*60=1800),
+The above example says "run for 30 minutes max (``-B`` 30*60=1800),
 poll for status (``-P``) every 60 seconds".
 
 Poll mode is smart so all jobs will be started before polling will begin on any machine.

docsite/rst/intro_configuration.rst

@@ -184,12 +184,12 @@ command_warnings
 
 .. versionadded:: 1.8
 
-By default since Ansible 1.8, Ansible will warn when usage of the shell and
-command module appear to be simplified by using a default Ansible module
-instead.  This can include reminders to use the 'git' module instead of
-shell commands to execute 'git'.  Using modules when possible over arbitrary
-shell commands can lead to more reliable and consistent playbook runs, and
-also easier to maintain playbooks::
+By default since Ansible 1.8, Ansible will issue a warning when the shell or 
+command module is used and the command appears to be similar to an existing 
+Ansible module. For example, this can include reminders to use the 'git' module
+instead of shell commands to execute 'git'.  Using modules when possible over 
+arbitrary shell commands can lead to more reliable and consistent playbook runs, 
+and also easier to maintain playbooks::
 
     command_warnings = False
 

docsite/rst/playbooks_intro.rst

@@ -73,10 +73,9 @@ 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
+When working with tasks that have really long parameters or modules that take 
+many parameters, you can break tasks items over multiple lines to improve the 
+structure. Below is another version of the above example but using
 YAML dictionaries to supply the modules with their ``key=value`` arguments.::
 
     ---
@@ -259,8 +258,8 @@ which is totally ok if the command is something like
 be used to make these modules also idempotent.
 
 Every task should have a ``name``, which is included in the output from
-running the playbook.   This is output for humans, so it is
-nice to have reasonably good descriptions of each task step.  If the name
+running the playbook.   This is human readable output, and so it is 
+useful to have provide good descriptions of each task step.  If the name
 is not provided though, the string fed to 'action' will be used for
 output.
 
@@ -365,9 +364,9 @@ The things listed in the ``notify`` section of a task are called
 handlers.
 
 Handlers are lists of tasks, not really any different from regular
-tasks, that are referenced by a globally unique name.  Handlers are
-what notifiers notify.  If nothing notifies a handler, it will not
-run.  Regardless of how many things notify a handler, it will run only
+tasks, that are referenced by a globally unique name, and are notified 
+by notifiers.  If nothing notifies a handler, it will not
+run.  Regardless of how many tasks notify a handler, it will run only
 once, after all of the tasks complete in a particular play.
 
 Here's an example handlers section::

docsite/rst/playbooks_roles.rst

@@ -9,8 +9,10 @@ Introduction
 While it is possible to write a playbook in one very large file (and you might start out learning playbooks this way),
 eventually you'll want to reuse files and start to organize things.
 
-At a basic level, including task files allows you to break up bits of configuration policy into smaller files.  Task includes 
-pull in tasks from other files.  Since handlers are tasks too, you can also include handler files from the 'handlers:' section.
+At a basic level, including task files allows you to break up bits of 
+configuration policy into smaller files.  Task includes pull in tasks from other 
+files.  Since handlers are tasks too, you can also include handler files from 
+the 'handler' section.
 
 See :doc:`playbooks` if you need a review of these concepts.
 
@@ -57,8 +59,9 @@ Include directives look like this, and can be mixed in with regular tasks in a p
 
 You can also pass variables into includes.  We call this a 'parameterized include'.
 
-For instance, if deploying multiple wordpress instances, I could
-contain all of my wordpress tasks in a single wordpress.yml file, and use it like so::
+For instance, to deploy to multiple wordpress instances, I could
+encapsulate all of my wordpress tasks in a single wordpress.yml file, and use 
+it like so::
 
    tasks:
      - include: wordpress.yml wp_user=timmy