Various docs cleanup.

docsite/latest/rst/developing_api.rst

@@ -2,9 +2,16 @@ Python API
 ==========
 
 There are several interesting ways to use Ansible from an API perspective.   You can use
-the Ansible python API to control nodes, you can extend Ansible to respond to various python events,
-and you can plug in inventory data from external data sources.  Ansible is written in its own
-API so you have a considerable amount of power across the board.  This chapter discusses the Python API.
+the Ansible python API to control nodes, you can extend Ansible to respond to various python events, you can
+write various plugins, and you can plug in inventory data from external data sources.  This document
+covers the Runner and Playbook API at a basic level.
+
+If you are looking to use Ansible programatically from something other than Python, trigger events asynchronously, 
+or have access control and logging demands, take a look at `AnsibleWorks AWX <http://ansibleworks.com/ansibleworks-awx>`_ 
+as it has a very nice REST API that provides all of these things at a higher level.
+
+Ansible is written in its own API so you have a considerable amount of power across the board.  
+This chapter discusses the Python API.
 
 .. contents:: `Table of contents`
    :depth: 2

docsite/latest/rst/developing_modules.rst

@@ -4,19 +4,24 @@ Developing Modules
 Ansible modules are reusable units of magic that can be used by the Ansible API,
 or by the `ansible` or `ansible-playbook` programs.
 
+See :doc:`modules` for a list of various ones developed in core.
+
 Modules can be written in any language and are found in the path specified
 by `ANSIBLE_LIBRARY` or the ``--module-path`` command line option.
 
+Should you develop an interesting Ansible module, consider sending a pull request to the
+`github project <http://github.com/ansible/ansible>`_ to see about getting your module
+included in the core project.
+
 .. contents::
    :depth: 2
 
-
 .. _module_dev_tutorial:
 
 Tutorial
 ````````
 
-Let's build a module to get and set the system time.  For starters, let's build
+Let's build a very-basic module to get and set the system time.  For starters, let's build
 a module that just outputs the current time.
 
 We are going to use Python here but any language is possible.  Only File I/O and outputing to standard

docsite/latest/rst/developing_plugins.rst

@@ -4,11 +4,11 @@ Developing Plugins
 .. contents::
    :depth: 2
 
-Ansible is pluggable in a lot of other ways seperate from inventory scripts and callbacks.  Many of these features are there to cover
-fringe use cases and are infrequently needed, and others are pluggable simply because they are there to implement core features
+Ansible is pluggable in a lot of other ways seperate from inventory scripts and callbacks.  Many of these features are there to cover fringe use cases and are infrequently needed, and others are pluggable simply because they are there to implement core features
 in ansible and were most convient to be made pluggable.
 
-This section will explore these features, though they are generally not common in terms of things people would look to extend.
+This section will explore these features, though they are generally not common in terms of things people would look to extend quite
+as often.
 
 .. _developing_connection_type_plugins:
 
@@ -22,8 +22,7 @@ Carrier Pigeon?) it's as simple as copying the format of one of the existing mod
 directory.   The value of 'smart' for a connection allows selection of paramiko or openssh based on system capabilities, and chooses
 'ssh' if OpenSSH supports ControlPersist, in Ansible 1.2.1 an later.  Previous versions did not support 'smart'.
 
-More documentation on writing connection plugins is pending, though you can jump into lib/ansible/runner/connection_plugins and figure
-things out pretty easily.
+More documentation on writing connection plugins is pending, though you can jump into lib/ansible/runner/connection_plugins and figure things out pretty easily.
 
 .. _developing_lookup_plugins:
 

docsite/latest/rst/playbooks.rst

@@ -92,7 +92,7 @@ For each play in a playbook, you get to choose which machines in your infrastruc
 to target and what remote user to complete the steps (called tasks) as.
 
 The `hosts` line is a list of one or more groups or host patterns,
-separated by colons, as described in the :ref:`patterns`
+separated by colons, as described in the :ref:`intro_patterns`
 documentation.  The `remote_user` is just the name of the user account::
 
     ---

docsite/latest/rst/playbooks_acceleration.rst

@@ -6,10 +6,12 @@ Accelerated Mode
 
 .. versionadded:: 1.3
 
-While SSH using the ControlPersist feature is quite fast and scalable, there is a certain amount of overhead involved in
-using SSH connections.  
+While OpenSSH using the ControlPersist feature is quite fast and scalable, there is a certain amount of overhead involved in
+using SSH connections.  If you are running on a platform that doesn't have ControlPersist support (such as an EL6 control
+machine), you'll probably be even more interested in options.
 
-Accelerate mode is there to help connections work faster, but still uses SSH for initial secure key exchange.
+Accelerate mode is there to help connections work faster, but still uses SSH for initial secure key exchange.  There is no
+additional public key infrastructure to manage, and this does not require things like NTP or even DNS.
 
 Accelerated mode can be anywhere from
 2-6x faster than SSH with ControlPersist enabled, and 10x faster than paramiko.

docsite/latest/rst/playbooks_environment.rst

@@ -7,9 +7,8 @@ Setting the Environment (and Working With Proxies)
 .. versionadded:: 1.1
 
 It is quite possible that you may need to get package updates through a proxy, or even get some package
-updates through a proxy and access other packages not through a proxy.  
-
-Occasionally a script you might wish to call may also need certain environment variables set.
+updates through a proxy and access other packages not through a proxy.  Or maybe a script you might wish to 
+call may also need certain environment variables set to run properly.
 
 Ansible makes it easy for you to configure your environment by using the 'environment' keyword.  Here is an example::
 

docsite/latest/rst/playbooks_loops.rst

@@ -4,7 +4,10 @@ Loops
 .. contents::
    :depth: 2
 
-All about how to use loops in playbooks.
+Often you'll want to do many things in one task, such as create a lot of users, install a lot of packages, or
+repeat a polling step until a certain result is reached.
+
+This chapter is all about how to use loops in playbooks.
 
 .. _standard_loops:
 

docsite/latest/rst/playbooks_prompts.rst

@@ -4,14 +4,16 @@ Prompts
 .. contents::
    :depth: 2
 
-You may wish to prompt the user for certain input, and can
-do so with the similarly named 'vars_prompt' section.  
+When running a playbook, you may wish to prompt the user for certain input, and can
+do so with the 'vars_prompt' section.  
 
-A common use for this might be for sensitive data.
+A common use for this might be for asking for sensitive data that you do not want to record.
 
 This has uses beyond security, for instance, you may use the same playbook for all
 software releases and would prompt for a particular release version
-in a push-script::
+in a push-script.
+
+Here is a most basic example::
 
     ---
     - hosts: all
@@ -23,8 +25,6 @@ in a push-script::
         quest: "what is your quest?"
         favcolor: "what is your favorite color?"
 
-There are full examples of both of these items in the github examples/playbooks directory.
-
 If you have a variable that changes infrequently, it might make sense to
 provide a default value that can be overridden.  This can be accomplished using
 the default argument::

docsite/latest/rst/playbooks_tags.rst

@@ -4,7 +4,7 @@ Tags
 .. contents::
    :depth: 2
 
-If you have a large playbook it may become useful to be able to run a
+If you have a large playbook it may become useful to be able to run a 
 specific part of the configuration without running the whole playbook.  
 
 Both plays and tasks support a "tags:" attribute for this reason.
@@ -28,12 +28,12 @@ If you wanted to just run the "configuration" and "packages" part of a very long
 
     ansible-playbook example.yml --tags "configuration,packages"
 
-You may also apply takes to roles:
+You may also apply takes to roles::
 
     roles:
       - { role: webserver, port: 5000, tags: [ 'web', 'foo' ] }
 
-And you may also tag basic include statements:
+And you may also tag basic include statements::
 
     - include: foo.yml tags=web,foo