Plugin doc update edits for #30490 (#30889)

* Edit pass 1 for #30490 - command line tools and developing plugins.

* Continuing edit pass for #30490. WIP

* Last round of copy edits for #30490.

docs/docsite/rst/command_line_tools.rst

@@ -2,7 +2,7 @@ Command Line Tools
 ==================
 
 Most users are familiar with `ansible` and `ansible-playbook`, but those are not the only utilities Ansible provides.
-Below you have the complate list, each page has the detailed swtiches and options that each tool supports and a short description of their purpose.
+Below you is a complete list of Ansible utilities. Each page contains a description of the utility and a listing of supported parameters.	
 
 .. toctree:: :maxdepth: 1
     :glob:

docs/docsite/rst/dev_guide/developing_plugins.rst

@@ -3,22 +3,19 @@ Developing Plugins
 
 .. contents:: Topics
 
-Plugins are pieces of code that augment Ansible's core functionality. Ansible ships with a number of handy plugins, and you can easily write your own.
+Plugins are pieces of code that augment Ansible's core functionality. Ansible ships with a number of handy plugins, and you can easily write your own. This section describes the various types of Ansible  plugins and how to implement them.
-This section describes the various types of plugins and how to implement them.
 
 .. _plugin_guidelines:
 
 General Guidelines
 ------------------
 
-Some things that should apply to any type of plugin you develop.
+This section lists some things that should apply to any type of plugin you develop.
 
 Raising Errors
 ``````````````
 
-In general, errors encountered during execution should be returned by raising AnsibleError() or similar class with a message describing the error.
+In general, errors encountered during execution should be returned by raising AnsibleError() or similar class with a message describing the error. When wrapping other exceptions into error messages, you should always use the `to_text` Ansible function to ensure proper string compatiblity across Python versions:
-When wrapping other exceptions into error messages you should always use the `to_text` Ansible function to ensure proper string compatiblity across
-Python versions:
 
 .. code-block:: python
 
@@ -31,35 +28,32 @@ Python versions:
 
 Check the different AnsibleError objects and see which one applies the best to your situation.
 
-String encoding
+String Encoding
 ```````````````
-Any strings returned by your plugin that could ever contain non-ASCII characters must be converted into Python's unicode type
+Any strings returned by your plugin that could ever contain non-ASCII characters must be converted into Python's unicode type because the strings will be run through jinja2.  To do this, you can use:
-because the strings will be run through jinja2.  To do this, you can use:
 
 .. code-block:: python
 
     from ansible.module_utils._text import to_text
     result_string = to_text(result_string)
 
-Plugin configuration
+Plugin Configuration
 ````````````````````
 
-Starting in 2.4 and going forward, we are unifying how each plugin type is configured and how they get those settings, plugins will be able to 'declare'
+Starting with Ansible version 2.4, we are unifying how each plugin type is configured and how they get those settings.  Plugins will be able to declare their requirements and have Ansible provide them with a resolved'configuration. Starting with Ansible 2.4 both callback and connection type plugins can use this system. 
-their needs and have Ansible provide them with the 'resolved' configuration. As of 2.4 both Callback and Connection type plugins can use this system,
-most plugins will be able to use  `self._options[<optionname>]` to access the settings, except callbacks that due to prexisting collsion
-use `self._plugin_optoins[<optionname>]`.
 
-Plugins that supprot docs (see `ansible-doc` for the list) are now required to provide documentation to be considered for merge into the Ansible repo.
+Most plugins will be able to use  `self._options[<optionname>]` to access the settings, except callbacks that use `self._plugin_options[<optionname>]`.
 
-Also be aware that if you inherit from a plugin you must ALSO document the optoins it takes, either via a documentation fragment or as a copy.
+Plugins that support embedded documentation (see `ansible-doc` for the list) are now required to provide well-formed doc strings to be considered for merge into the Ansible repo.
+
+If you inherit from a plugin, you must document the options it takes, either via a documentation fragment or as a copy.
 
 .. _developing_callbacks:
 
 Callback Plugins
 ----------------
 
-See :doc: plugins/callback as to what they are and how to use them. This section explains how to use them.
+Callback plugins enable adding new behaviors to Ansible when responding to events. By default, callback plugins control most of the output you see when running the command line programs.
-
 
 Callback plugins are created by creating a new class with the Base(Callbacks) class as the parent:
 
@@ -76,8 +70,8 @@ For a complete list of methods that you can override, please see ``__init__.py``
 `lib/ansible/plugins/callback <https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/callback>`_ directory.
 
 
-The following example shows a modified example Ansible's timer plugin is implemented,
+The following is a modified example of how Ansible's timer plugin is implemented,
-but with an extra option so you can see how configuration works in Ansible >= 2.4:
+but with an extra option so you can see how configuration works in Ansible version 2.4 and later:
 
 .. code-block:: python
 
@@ -135,67 +129,68 @@ but with an extra option so you can see how configuration works in Ansible >= 2.
           r_seconds = runtime.seconds - (minutes * 60)
           return runtime.days, runtime.seconds // 3600, minutes, r_seconds
 
-      # this is only event we care about for display, when the play shows it's summary stats, the rest are ignored by the base class
+      # this is only event we care about for display, when the play shows its summary stats; the rest are ignored by the base class
       def v2_playbook_on_stats(self, stats):
           end_time = datetime.now()
           runtime = end_time - self.start_time
 
-          # Shows the usage of a config option declared in the DOCUMENTATION variable, Ansible will have set it when it loads the plugin.
+          # Shows the usage of a config option declared in the DOCUMENTATION variable. Ansible will have set it when it loads the plugin.
-          # Also note the use of the display object to print to screen, available to all callbacks, you should prefer this over printing yoruself
+          # Also note the use of the display object to print to screen. This is available to all callbacks, and you should use this over printing yourself
           self._display.display(self._plugin_options['format_string'] % (self._days_hours_minutes_seconds(runtime)))
 
-Note that the CALLBACK_VERSION and CALLBACK_NAME definitions are required for properly functioning plugins for Ansible >=2.0.
+Note that the CALLBACK_VERSION and CALLBACK_NAME definitions are required for properly functioning plugins for Ansible version 2.0 and later. CALLBACK_TYPE is mostly needed to distinguish 'stdout' plugins from the rest, since you can only load one plugin that writes to stdout.
-CALLBACK_TYPE is mostly needed to distinguish 'stout' plugins from the rest, as you can only load one of that type.
 
 .. _developing_connection_plugins:
 
 Connection Plugins
 ------------------
 
-By default, Ansible ships with a 'paramiko' SSH, native ssh (just called 'ssh'), 'local' connection type, and there are also some minor players like 'chroot' and 'jail'.  All of these can be used in playbooks and with /usr/bin/ansible to decide how you want to talk to remote machines.  The basics of these connection types
+Connection plugins allow Ansible to connect to the target hosts so it can execute tasks on them. Ansible ships with many connection plugins, but only one can be used per host at a time.
-are covered in the :doc:`../intro_getting_started` section.  Should you want to extend Ansible to support other transports (SNMP, Message bus, etc) it's as simple as copying the format of one of the existing modules and dropping it into the connection plugins
-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 and later.  Previous versions did not support 'smart'.
 
-More documentation on writing connection plugins is pending, though you can jump into
+By default, Ansible ships with several plugins. The most commonly used are the 'paramiko' SSH, native ssh (just called 'ssh'), and 'local' connection types.  All of these can be used in playbooks and with /usr/bin/ansible to decide how you want to talk to remote machines.  
-`lib/ansible/plugins/connection <https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/connection>`_ and figure things out pretty easily.
+
+The basics of these connection types are covered in the :doc:`../intro_getting_started` section.  
+
+Should you want to extend Ansible to support other transports (SNMP, Message bus, etc) it's as simple as copying the format of one of the existing modules and dropping it into the connection plugins directory.  
+
+Ansible version 2.1 introduced the 'smart' connection plugin. The 'smart' connection type allows Ansible to automatically select either the 'paramiko' or 'openssh' connection plugin based on system capabilities, or the 'ssh' connection plugin if OpenSSH supports ControlPersist. 
+
+For examples on how to implement a connection plug in, see the source code here: 
+`lib/ansible/plugins/connection <https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/connection>`_.
 
 .. _developing_inventory_plugins:
 
 Inventory Plugins
 -----------------
 
-Added in Ansible 2.4 they are in charge of parsing inventory sources and forming the 'in memory' representation of the Inventory.
+Inventory plugins were added in Ansible version 2.4. Inventory plugins parse inventory sources and form an in memory representation of the inventory.
 
-They are invoked via the InventoryManager and are given access to any existing inventory data added previouslly,
+Inventory plugins are invoked via the InventoryManager and are given access to any existing inventory data. They are given an 'inventory source' as supplied to Ansible (via config/options/defaults/etc), which they can either ignore
-they are given an 'inventory source' as supplied to Ansible (via config/optoins/defaults/etc), which they can ignore
+by returning false from the `verify_file` method, or attempting to parse (with the `parse` method) and return an `AnsibleParserError` on failure.
-(return false from the `verify_file` method), or attempt to parse (via `parse` method) and return an `AnsibleParserError` on failure.
 
 .. code-block:: python
 
    def parse(self, inventory, loader, path, cache=True):
         pass # your code goes here
 
-The parameters are:
+Inventory plugins take the following parameters:
 
  * inventory: inventory object with existing data and the methods to add hosts/groups/variables to inventory
- * loader: Ansible's DataLoader, it can read files, auto load JSON/YAML and decrypt vaulted data, it also caches read filesh.
+ * loader: Ansible's DataLoader. The DataLoader can read files, auto load JSON/YAML and decrypt vaulted data, and cache read files.
- * path: string with inventory source (normally a path, but not required)
+ * path: string with inventory source (this is usually a path, but is not required)
- * cache: hint to the plugin if it should use or avoid caches (Cache plugin and/or loader)
+ * cache: indicates whether the plugin should use or avoid caches (cache plugin and/or loader)
 
-Inventory sources are strings, most of the time they correspond to a file path, but can also be a comma separated list,
+Inventory sources are strings. They usually correspond to a file path, but they can also be a comma separated list,
-a uri or anything your plugin can use as input.
+a URI, or anything your plugin can use as input.
-The 'inventory source' provided can be either a string (`host_list` plugin), a data file (like consumed by the `yaml` and `ini` plugins),
+The 'inventory source' provided can be either a string (`host_list` plugin), a data file (like consumed by the `yaml` and `ini` plugins), a configuration file (see `virtualbox` and `constructed`) or even a script or executable (the `script` uses those).
-a configuration file (see `virtualbox` and `constructed`) or even a script or executable (the `script` uses those) which is how 'inventory scripts' work.
 
-Inventory plugins can also use the configured Cache plugin to store and retrieve data to avoid costly external calls,
+When using the 'persistent' cache, inventory plugins can also use the configured cache plugin to store and retrieve data to avoid costly external calls. 
-of course this only works if using a 'persistent' cache (i.e not the memory one).
 
-Be aware that inventory plugins normally only execute at the start of the run, before playbooks/plays and roles are found,
+Inventory plugins normally only execute at the start of a run, before playbooks/plays and roles are found,
 but they can be 're-executed' via the `meta: refresh_inventory` task, which will clear out the existing inventory and rebuild it.
 
-More documentation on writing inventory plugins is pending, though you can jump into
+For examples on how to implement a connection plug in, see the source code here:
-`lib/ansible/plugins/inventory <https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/inventory>`_ and figure things out pretty easily.
+`lib/ansible/plugins/inventory <https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/inventory>`_.
 
 .. _developing_lookup_plugins:
 
@@ -208,7 +203,7 @@ Here's a simple lookup plugin implementation - this lookup returns the contents
 
 .. code-block:: python
 
-  # python 3ish headers, required if submitting to Ansible
+  # python 3 headers, required if submitting to Ansible
   from __future__ import (absolute_import, division, print_function)
   __metaclass__ = type
 
@@ -225,7 +220,7 @@ Here's a simple lookup plugin implementation - this lookup returns the contents
               required: True
           notes:
             - if read in variable context, the file can be interpreted as YAML if the content is valid to the parser.
-            - this lookup does not understand 'globing', use the fileglob lookup instead.
+            - this lookup does not understand 'globing' - use the fileglob lookup instead.
   """
   from ansible.errors import AnsibleError, AnsibleParserError
   from ansible.plugins.lookup import LookupBase
@@ -269,7 +264,7 @@ Here's a simple lookup plugin implementation - this lookup returns the contents
 
           return ret
 
-An example of how this lookup is called::
+The following is an example of how this lookup is called::
 
   ---
   - hosts: all
@@ -282,19 +277,18 @@ An example of how this lookup is called::
 
 For more example lookup plugins, check out the source code for the lookup plugins that are included with Ansible here: `lib/ansible/plugins/lookup <https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/lookup>`_.
 
-For usage examples of lookup plugins, see `Using Lookups <http://docs.ansible.com/ansible/playbooks_lookups.html>`_.
+For more usage examples of lookup plugins, see `Using Lookups <http://docs.ansible.com/ansible/playbooks_lookups.html>`_.
 
 .. _developing_vars_plugins:
 
 Vars Plugins
 ------------
 
-Playbook constructs like 'host_vars' and 'group_vars' work via 'vars' plugins.
+Vars plugins inject additional variable data into Ansible runs that did not come from an inventory source, playbook, or command line. Playbook constructs like 'host_vars' and 'group_vars' work using vars plugins.
-They inject additional variable data into ansible runs that did not come from an inventory source, playbook, or command line.
 
-Vars plugins got rewritten in 2.4 and had been semi-functional since 2.0.
+Vars plugins were partially implented in Ansible 2.0 and rewritten to be fully implemented starting with Ansible 2.4.
 
-Older pugins used a `run` method as their main body/work:
+Older plugins used a `run` method as their main body/work:
 
 .. code-block:: python
 
@@ -302,7 +296,7 @@ Older pugins used a `run` method as their main body/work:
         pass # your code goes here
 
 
-But Ansible 2.0 did not pass passwords to them so vaults were unavilable.
+Ansible 2.0 did not pass passwords to older plugins, so vaults were unavilable.
 Most of the work now  happens in the `get_vars` method which is called from the VariableManager when needed.
 
 .. code-block:: python
@@ -312,18 +306,16 @@ Most of the work now  happens in the `get_vars` method which is called from the
 
 The parameters are:
 
- * loader: Ansible's DataLoader, it can read files, auto load JSON/YAML and decrypt vaulted data, it also caches read filesh.
+ * loader: Ansible's DataLoader. The DataLoader can read files, auto load JSON/YAML and decrypt vaulted data, and cache read files.
- * path: this is 'directory data' for every inventory source and the current play's playbook directory, so they can search for data
+ * path: this is 'directory data' for every inventory source and the current play's playbook directory, so they can search for data in reference to them. `get_vars` will be called at least once per available path.
-         in reference to them, `get_vars` will be called at least once per available path.
+ * entities: these are host or group names that are pertinent to the variables needed. The plugin will get called once for hosts and again for groups.
- * entities: these are host or group names that are pertinent to the variables needed, the plugin will get called once for hosts and again for groups.
 
-This method just needs to return a dictionary structure with the pertinent variables.
+This `get vars` method just needs to return a dictionary structure with the variables.
 
-Since Ansible 2.4, vars plugins execute as needed when preparing to execute a task, this avoids the costly 'always execute' that used
+Since Ansible version 2.4, vars plugins only execute as needed when preparing to execute a task. This avoids the costly 'always execute' behavior that occurred during inventory construction in older versions of Ansible.
-to happend during inventory construction.
 
-More documentation on writing vars plugins is pending, though you can jump into
+For implementation examples of vars plugins, check out the source code for the vars plugins that are included with Ansible:
-`lib/ansible/plugins/vars <https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/vars>`_ and figure things out pretty easily.
+`lib/ansible/plugins/vars <https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/vars>`_  .
 
 
 .. _developing_filter_plugins:

docs/docsite/rst/intro_configuration.rst

@@ -4,7 +4,7 @@ Configuration
 .. contents:: Topics
 
 
-There are several ways to control Ansible settings, this is a brief descriptoin of them.
+This topic describes how to control Ansible settings.
 
 
 .. _the_configuration_file:
@@ -20,16 +20,15 @@ The stock configuration should be sufficient for most users, but there may be re
 Getting the latest configuration
 ````````````````````````````````
 
-If installing ansible from a package manager, the latest ansible.cfg should be present in /etc/ansible, possibly
+If installing Ansible from a package manager, the latest ansible.cfg file should be present in /etc/ansible, possibly
 as a ".rpmnew" file (or other) as appropriate in the case of updates.
 
-If you have installed from pip or from source, however, you may want to create this file in order to override
+If you installed Ansible from pip or from source, you may want to create this file in order to override
 default settings in Ansible.
 
-An example file is availble `ansible.cfg in source control <https://raw.github.com/ansible/ansible/devel/examples/ansible.cfg>`_
+An `example file is available on Github <https://raw.github.com/ansible/ansible/devel/examples/ansible.cfg>`_.
 
-For more details and a full listing of available configurations go to :doc:configuration or (starting at Ansible 2.4)
+For more details and a full listing of available configurations go to :doc:configuration. Starting with Ansible version 2.4, you can use the :doc:`ansible-config` command line utility to list your available options and inspect the current values.
-you can use the :doc:`ansible-config` command line utility to list your available options and inspect the current values.
 
 For in depth details you check out :doc:`config`.
 
@@ -37,10 +36,10 @@ For in depth details you check out :doc:`config`.
 Environmental configuration
 +++++++++++++++++++++++++++
 
-Ansible also allows configuration of settings via environment variables.
+Ansible also allows configuration of settings using environment variables.
 If these environment variables are set, they will override any setting loaded from the configuration file.
 
-You can get a full listing of available variables from :doc:`config`.
+You can get a full listing of available environment variables from :doc:`config`.
 
 .. _command_line_configuration:
 

docs/docsite/rst/playbooks_lookups.rst

@@ -1,17 +1,13 @@
 Lookups
 -------
 
-Lookup plugins allow access of data in Ansible from outside sources. Like all templating, these plugins are evaluated on the Ansible control
+Lookup plugins allow access to outside data sources. Like all templating, these plugins are evaluated on the Ansible control machine, and can include reading the filesystem as well as contacting external datastores and services. This data is then made available using the standard templating system in Ansible. 
-machine, and can include reading the filesystem but also contacting external datastores and services.
-
-These values are then made available using the standard templating system in Ansible,
-and are typically used to load variables or templates with information from those systems.
 
 .. note::
     - Lookups occur on the local computer, not on the remote computer.
-    - They are executed with a cwd relative to the role or play, as opposed to local tasks which are executed with the cwd of the executed script.
+    - They are executed with in the directory containing the role or play, as opposed to local tasks which are executed with the directory of the executed script.
-    - Since 1.9 you can pass wantlist=True to lookups to use in jinja2 template "for" loops.
+    - Since Ansible version 1.9, you can pass wantlist=True to lookups to use in jinja2 template "for" loops.
-    - This is considered an advanced feature, you should try to feel comfortable with Ansible plays before incorporating them.
+    - Lookups are an advanced feature. You should have a good working knowledge of Ansible plays before incorporating them.
 
 .. warning:: Some lookups pass arguments to a shell. When using variables from a remote/untrusted source, use the `|quote` filter to ensure safe usage.
 
@@ -24,7 +20,7 @@ Intro to Lookups: Getting File Contents
 
 The file lookup is the most basic lookup type.
 
-Contents can be read off the filesystem as follows::
+Contents can be read from the filesystem as follows::
 
     ---
     - hosts: all
@@ -42,18 +38,14 @@ The Password Lookup
 
 .. note::
 
-    A great alternative to the password lookup plugin, if you don't need to generate random passwords on a per-host basis, would be to use :doc:`playbooks_vault`.  Read the documentation there and consider using it first, it will be more desirable for most applications.
+    We recommend using :doc:`playbooks_vault` instead of the password lookup plugin if you don't need to generate random passwords on a per-host basis.
 
-``password`` generates a random plaintext password and stores it in
+The ``password lookup`` plugin generates a random plaintext password and stores it in
 a file at a given filepath.
 
-(Docs about crypted save modes are pending)
+If the file already exists, it will retrieve its contents, behaving just like with_file. Usage of variables like "{{ inventory_hostname }}" in the filepath can be used to set up random passwords per host (which simplifies password management in 'host_vars' variables).
 
-If the file exists previously, it will retrieve its contents, behaving just like with_file. Usage of variables like "{{ inventory_hostname }}" in the filepath can be used to set
+A special case is using ``/dev/null`` as a path. The password lookup will generate a new random password each time, but will not write it to ``/dev/null``. This can be used when you need a password without storing it on the controller.
-up random passwords per host (which simplifies password management in 'host_vars' variables).
-
-A special case is using ``/dev/null`` as a path. The password lookup will generate a new random password each time, but will not write it to ``/dev/null``. This can be used when you need a password
-without storing it on the controller.
 
 Generated passwords contain a random mix of upper and lowercase ASCII letters, the
 numbers 0-9 and punctuation (". , : - _"). The default length of a generated password is 20 characters.
@@ -74,9 +66,9 @@ This length can be changed by passing an extra parameter::
 
 .. note:: If the file already exists, no data will be written to it. If the file has contents, those contents will be read in as the password. Empty files cause the password to return as an empty string.
 
-Caution: Since this runs on the ansible host as the user running the playbook, and "become" does not apply, the target file must be readable by the playbook user, or, if it does not exist, the playbook user must have sufficient privileges to create it. (So, for example, attempts to write into areas such as /etc will fail unless the entire playbook is being run as root).
+.. warning:: Since the password lookup runs on the Ansible host as the user running the playbook, and "become" does not apply, the target file must be readable by the playbook user, or, if it does not exist, the playbook user must have sufficient privileges to create it. Attempts to write into areas such as /etc will fail unless the entire playbook is being run as root.
 
-Starting in version 1.4, password accepts a "chars" parameter to allow defining a custom character set in the generated passwords. It accepts comma separated list of names that are either string module attributes (ascii_letters,digits, etc) or are used literally::
+Starting in Ansible version 1.4, password accepts a "chars" parameter to allow defining a custom character set in the generated passwords. It accepts comma separated list of names that are either string module attributes (such as ascii_letters or digits) or are used literally::
 
     ---
     - hosts: all
@@ -100,7 +92,7 @@ Starting in version 1.4, password accepts a "chars" parameter to allow defining
 
         # (...)
 
-To enter comma use two commas ',,' somewhere - preferably at the end. Quotes and double quotes are not supported.
+To enter a comma use two commas ',,' somewhere - preferably at the end. Quotes and double quotes are not supported.
 
 .. _passwordstore_lookup:
 

docs/docsite/rst/plugins.rst

@@ -1,11 +1,11 @@
 Plugins
 =======
 
-Ansible uses a plugin architecture to enable a rich, flexible and expandible feature set.
+Plugins are pieces of code that augment Ansible's core functionality. Ansible uses a plugin architecture to enable a rich, flexible and expandible feature set.
-They are pieces of code that augment Ansible's core functionality.
+
 Ansible ships with a number of handy plugins, and you can easily write your own.
 
-There are many types of plugins, these are the most relevant ones:
+This section covers the various types of plugins that are included with Ansible:
 
 .. toctree:: :maxdepth: 1
     :glob:
@@ -14,8 +14,6 @@ There are many types of plugins, these are the most relevant ones:
     playbooks_filters
     playbooks_tests
 
-Most of the time you are using them without having to know about them, but when you want to change certain behaviours you need to know how to enable,
-activate or trigger each type.
 
 .. seealso::
 

docs/docsite/rst/plugins/action.rst

@@ -1,18 +1,15 @@
 Action Plugins
 ---------------
 
-These plugins act in conjunction with :doc:`modules <../modules>` to execute the actions required by playbook tasks.
+Action plugins act in conjunction with :doc:`modules <../modules>` to execute the actions required by playbook tasks.
-They mostly execute automatically in the background doing prerequisite work for the modules of the same to be able to execute.
+They usually execute automatically in the background doing prerequisite work before modules execute.
 
-The 'normal' action plugin takes care of modules that do not already have an action plugin.
+The 'normal' action plugin is used for modules that do not already have an action plugin.
-
-Enabling Vars Plugins
-+++++++++++++++++++++
-
-You can activate a custom action plugins by either dropping it into a ``action_plugins`` directory adjacent to your play or inside a role
-or by putting it in one of the action plugin directory sources configured in :doc:`ansible.cfg <../config>`.
 
+Enabling Action Plugins
++++++++++++++++++++++++
 
+You can enable a custom action plugin by either dropping it into the ``action_plugins`` directory adjacent to your play, inside a role, or by putting it in one of the action plugin directory sources configured in :doc:`ansible.cfg <../config>`.
 
 .. seealso::
 

docs/docsite/rst/plugins/cache.rst

@@ -4,11 +4,10 @@
 Cache Plugins
 -------------
 
-This plugin implelents a backend caching mechanism for Ansible to store gathered facts or inventory source data
+Cache plugin implement a backend caching mechanism that allows Ansible to store gathered facts or inventory source data
-to avoid the cost of retrieving them from source.
+without the performance hit of retrieving them from source.
 
-The default plugin is the :doc:`memory <cache/memory>` plugin which will only cache the data for the current execution of Ansible.
+The default cache plugin is the :doc:`memory <cache/memory>` plugin, which only caches the data for the current execution of Ansible. Other plugins with persistent storage are available to allow caching the data across runs.
-Other plugins with persistent storage are available to allow caching the data across runs.
 
 
 Enabling Cache Plugins
@@ -16,7 +15,7 @@ Enabling Cache Plugins
 
 Only one cache plugin can be active at a time.
 
-You can enable in configuration, either via environment variable:
+You can enable a cache plugin in the Ansible configuration, either via environment variable:
 
 .. code-block:: shell
 
@@ -29,14 +28,14 @@ or in the ``ansible.cfg`` file:
     [defaults]
     fact_caching=redis
 
-You will also need to setup other settings specific to each plugin, you can check the individual plugin documenattion
+You will also need to configure other settings specific to each plugin. Consult the individual plugin documentation
-or the ansible :doc:`configuration <../config>` for more details.
+or the Ansible :doc:`configuration <../config>` for more details.
 
 Plugin List
 +++++++++++
 
-You can use ``ansible-doc -t cache -l`` to see the list of available plugins,
+You can use ``ansible-doc -t cache -l`` to see the list of available plugins. 
-use ``ansible-doc -t cache <plugin name>`` to see specific documents and examples.
+Use ``ansible-doc -t cache <plugin name>`` to see specific documentation and examples.
 
 .. toctree:: :maxdepth: 1
     :glob:

docs/docsite/rst/plugins/callback.rst

@@ -16,9 +16,7 @@ Example Callback Plugins
 The :doc:`log_plays <callback/log_plays>` callback is an example of how to record playbook events to a log file,
 and the :doc:`mail callback/mail` callback sends email on playbook failures.
 
-The :doc:`osx_say <callback/oxs_say>` callback provided is particularly entertaining --
+The :doc:`osx_say <callback/oxs_say>` callback responds with computer synthesized speech on OS X in relation to playbook events.
-it will respond with computer synthesized speech on OS X in relation to playbook events,
-and is guaranteed to entertain and/or annoy coworkers.
 
 
 .. _enabling_callbacks:
@@ -26,13 +24,11 @@ and is guaranteed to entertain and/or annoy coworkers.
 Enabling Callback Plugins
 ++++++++++++++++++++++++++
 
-You can activate a custom callback by either dropping it into a ``callback_plugins`` directory adjacent to your play or inside a role
+You can activate a custom callback by either dropping it into a ``callback_plugins`` directory adjacent to your play,  inside a role, or by putting it in one of the callback directory sources configured in :doc:`ansible.cfg <../config>`.
-or by putting it in one of the callback directory sources configured in :doc:`ansible.cfg <../config>`.
 
-Plugins are loaded in alphanumeric order; for example, a plugin implemented in a file named `1_first.py` would run before a plugin file named `2_second.py`.
+Plugins are loaded in alphanumeric order. For example, a plugin implemented in a file named `1_first.py` would run before a plugin file named `2_second.py`.
 
-Most callbacks shipped with Ansible are disabled by default and need to be whitelisted in your :doc:`ansible.cfg <../config>` file in order to function.
+Most callbacks shipped with Ansible are disabled by default and need to be whitelisted in your :doc:`ansible.cfg <../config>` file in order to function. For example:
-For example:
 
 .. code-block:: ini
 
@@ -59,15 +55,15 @@ This only affects :doc:`../ansible-playbook` by default.
 Managing AdHoc
 ``````````````
 
-The :doc:`ansible <../ansible>` AdHoc command speifically uses a different callback plugin for stdout,
+The :doc:`ansible <../ansible>` AdHoc command specifically uses a different callback plugin for stdout,
-so there is an extra setting you need to enable it to use the stdout callback defined above, in :doc:`ansible.cfg <../config>`:
+so there is an extra setting in :doc:`ansible.cfg <../config>` you need to add to use the stdout callback defined above:
 
 .. code-block:: ini
 
     [defaults]
     bin_ansible_callbacks=True
 
-or as an environment variable:
+You can also set this as an environment variable:
 
 .. code-block:: shell
 
@@ -77,8 +73,8 @@ or as an environment variable:
 Plugin List
 +++++++++++
 
-You can use ``ansible-doc -t callback -l`` to see the list of available plugins,
+You can use ``ansible-doc -t callback -l`` to see the list of available plugins. 
-use ``ansible-doc -t callback <plugin name>`` to see specific documents and examples.
+Use ``ansible-doc -t callback <plugin name>`` to see specific documents and examples.
 
 
 .. toctree:: :maxdepth: 1

docs/docsite/rst/plugins/connection.rst

@@ -4,23 +4,21 @@
 Connection Plugins
 ------------------
 
-These plugins are in charge of enabling Ansible to connect to the target hosts so it can execute tasks on them.
+Connection plugins allow Ansible to connect to the target hosts so it can execute tasks on them. Ansible ships with many connection plugins, but only one can be used per host at a time.
-Ansible ships we many connection plugins but only one can be used per host at a time.
 
-By default, the configuration uses a 'smart' value, which means Ansible will decide to use the 'ssh' or 'paramiko' (python version of ssh client)
+By default, Ansible ships with several plugins. The most commonly used are the 'paramiko' SSH, native ssh (just called 'ssh'), and 'local' connection types.  All of these can be used in playbooks and with /usr/bin/ansible to decide how you want to talk to remote machines.  
-depending on what it detects on your system capabilities, it normally chooses 'ssh' if OpenSSH supports ControlPersist.
+
+The basics of these connection types are covered in the :doc:`../intro_getting_started` section.  
 
-The basics of these connection types are covered in the :doc:`../intro_getting_started` section.
 
 .. contents:: Topics
 
 .. _ssh_plugins:
 
-The ssh Plugins
+ssh Plugins
-++++++++++++++++
++++++++++++
 
-Since ssh is the default protocol used in system administration it is also the most used and prevalent in Ansible,
+Because ssh is the default protocol used in system administration and the protocol most used in Ansible, ssh options are included in the command line tools. See :doc:`../ansible-playbook` for more details.
-so much so that ssh options are included in the command line tools unlike other plugins, see :doc:`../ansible-playbook` for more details.
 
 
 .. _using_connection_plugins:
@@ -32,29 +30,30 @@ The transport can be changed via :doc:`configuration <../config>`, in the comman
 in your play or by setting the a connection variable (:ref:`ansible_connection`), most often, in your inventory.
 For example, for windows machines you might want o use the :doc:`winrm <connection/winrm>` plugin instead.
 
-Most connection plugins can operate with a minimum configuration, by defaul they use the :ref:`inventory_hostname` and defaults to find the target host.
+Most connection plugins can operate with a minimum configuration. By default they use the :ref:`inventory_hostname` and defaults to find the target host.
-Each plugin documents it's configuration options and how to set, the following are 'connection variables' common to most:
+
+Plugins are self-documenting. Each plugin should document its configuration options. The following are connection variables common to most connection plugins:
 
 :ref:ansible_host
     The name of the host to connect to, if different from the :ref:`inventory_hostname`.
 :ref:ansible_port
-    The ssh port number, for :doc:`ssh <connection/ssh>` and :doc:`paramiko <connection/paramiko>` it defaults to 22.
+    The ssh port number. For :doc:`ssh <connection/ssh>` and :doc:`paramiko <connection/paramiko>` the default value is 22.
 :ref:ansible_user
-    The default user name to log in as, most plugins defaul to the 'current user running Ansible'
+    The default user name to use for log in. Most plugins default to the current user running Ansible.
 
-Each plugin might also have a specific version that overrides the general one. i.e :ref:`ansible_ssh_host` for the :doc:`ssh <connection/ssh>` plugin.
+Each plugin might also have a specific version of a variable that overrides the general version. For example, :ref:`ansible_ssh_host` for the :doc:`ssh <connection/ssh>` plugin.
 
 Enabling Connection Plugins
 +++++++++++++++++++++++++++
 
-Should you want to extend Ansible to support other transports (SNMP, Message bus, etc) it's as simple as dropping a custom plugin
+You can extend Ansible to support other transports (such as SNMP or message bus) by dropping a custom plugin
 into the ``connection_plugins`` directory.
 
 Plugin List
 +++++++++++
 
-You can use ``ansible-doc -t connection -l`` to see the list of available plugins,
+You can use ``ansible-doc -t connection -l`` to see the list of available plugins.
-use ``ansible-doc -t connection <plugin name>`` to examine detailed documentation and examples.
+Use ``ansible-doc -t connection <plugin name>`` to see detailed documentation and examples.
 
 
 .. toctree:: :maxdepth: 1

docs/docsite/rst/plugins/inventory.rst

@@ -4,8 +4,7 @@
 Inventory Plugins
 -----------------
 
-Inventory plugins allow users to point at data sources to compile the inventory of hosts that Ansible uses to target it's tasks.
+Inventory plugins allow users to point at data sources to compile the inventory of hosts that Ansible uses to target tasks, either via the ``-i /path/to/file`` and/or ``-i 'host1, host2`` command line parameters or from other configuration sources.
-They control what happens when with ``-i /path/to/file`` and/or ``-i 'host1, host2`` when passed into Ansible (or from other configuration sources).
 
 .. _enabling_inventory_plugins:
 
@@ -13,15 +12,15 @@ Enabling Inventory Plugins
 ++++++++++++++++++++++++++
 
 Most inventory plugins shipped with Ansible are disabled by default and need to be whitelisted in your
-:doc:`ansible.cfg <../config>` file in order to function.  For example, this is how the default looks like:
+:doc:`ansible.cfg <../config>` file in order to function.  This is how the default whitelist looks in the
+config file that ships with Ansible:
 
 .. code-block:: ini
 
    [inventory]
    enable_plugins = host_list, script, yaml, ini
 
-This list also establishes the order in which each plugin tries to parse an inventory source (in the case 2 plugins can use the same source).
+This list also establishes the order in which each plugin tries to parse an inventory source. Any plugins left out of the list will not be considered, so you can 'optimize' your inventory loading by minimizing it to what you actually use. For example:
-Any plugins left out of the list will not be considered, so you can 'optimize' your inventory loading by minimizing it to what you actually use:
 
 .. code-block:: ini
 
@@ -32,8 +31,8 @@ Any plugins left out of the list will not be considered, so you can 'optimize' y
 Plugin List
 +++++++++++
 
-You can use ``ansible-doc -t inventory -l`` to see the list of available plugins,
+You can use ``ansible-doc -t inventory -l`` to see the list of available plugins. 
-use ``ansible-doc -t inventory <plugin name>`` to see specific documents and examples.
+Use ``ansible-doc -t inventory <plugin name>`` to see plugin-specific documentation and examples.
 
 .. toctree:: :maxdepth: 1
     :glob:

docs/docsite/rst/plugins/shell.rst

@@ -1,20 +1,15 @@
 Shell Plugins
 -------------
 
-These plugins work behind the scenes making sure the basic commands Ansible runs,
+Shell plugins work transparently to ensure that the basic commands Ansible runs are properly formated to work with the target machine.
-in order to be able to execute a task's action,
-are properly formated to work with the target machine.
-
-You normally don't have to wory about these plugins at all,
-unless you have a restricted or exotic setup,
-in which the default ``/bin/sh`` is not a POSIX compatible shell or not availble for execution.
 
 Enabling Shell Plugins
 ++++++++++++++++++++++
 
-You probably never need to do this, but aside from the defaul configuration settings in :doc:`../config`,
+.. warning:: These plugins should not be reconfigured unless you have a restricted or exotic setup
-you can use a 'connection variable' :ref:`ansible_shell_type` to select the plugin to use,
+             in which the default ``/bin/sh`` is not a POSIX compatible shell or not availble for execution. 
-you will also want to update the :ref:`ansible_executable` to match.
+
+In addition to modifying the default configuration settings in :doc:`../config`, you can use a 'connection variable' :ref:`ansible_shell_type` to select a shell plugin, and update the :ref:`ansible_executable` to match.
 
 .. seealso::
 

docs/docsite/rst/plugins/strategy.rst

@@ -4,14 +4,14 @@
 Strategy Plugins
 ----------------
 
-Strategy plugins control the flow of play execution, they handle task and host scheduleing.
+Strategy plugins control the flow of play execution by handling task and host scheduling.
 
 
-Enabling Cache Plugins
+Enabling Strategy Plugins
-++++++++++++++++++++++
++++++++++++++++++++++++++
 
-Only one strategy plugin can be used in a play, but you can use different ones for each play in a playbook or ansible run.
+Only one strategy plugin can be used in a play, but you can use different ones for each play in a playbook or Ansible run.
-The default is the :doc:`linear <strategy/linear>` plugin, you can change this default via :doc:`configuration <../config>`:
+The default is the :doc:`linear <strategy/linear>` plugin. You can change this default in Ansible :doc:`configuration <../config>` using an environment variable:
 
 .. code-block:: shell
 
@@ -24,7 +24,7 @@ or in the `ansible.cfg` file:
     [defaults]
     strategy=linear
 
-Or you can just speicfy the plugin in the play via the :ref:`strategy` keyword::
+You can also specify the strategy plugin in the play via the :ref:`strategy` keyword::
 
   - hosts: all
     strategy: debug
@@ -42,8 +42,8 @@ Or you can just speicfy the plugin in the play via the :ref:`strategy` keyword::
 Plugin List
 +++++++++++
 
-You can use ``ansible-doc -t strategy -l`` to see the list of available plugins,
+You can use ``ansible-doc -t strategy -l`` to see the list of available plugins. 
-use ``ansible-doc -t strategy <plugin name>`` to see specific documents and examples.
+Use ``ansible-doc -t strategy <plugin name>`` to see plugin-specific specific documentation and examples.
 
 
 .. toctree:: :maxdepth: 1

docs/docsite/rst/plugins/vars.rst

@@ -4,21 +4,23 @@
 Vars Plugins
 ------------
 
-They inject additional variable data into ansible runs that did not come from an inventory source, playbook, or command line.
+Vars plugins inject additional variable data into Ansible runs that did not come from an inventory source, playbook, or command line. Playbook constructs like 'host_vars' and 'group_vars' work using vars plugins.
-The :doc:`host_group_vars <vars/host_group_vars>` plugin shipped with Ansible provides reading variables from :ref:`host_vars` and :ref:`group_vars`.
+
+Vars plugins were partially implented in Ansible 2.0 and rewritten to be fully implemented starting with Ansible 2.4.
+
+The :doc:`host_group_vars <vars/host_group_vars>` plugin shipped with Ansible enables reading variables from :ref:`host_vars` and :ref:`group_vars`.
 
 
 Enabling Vars Plugins
 +++++++++++++++++++++
 
-You can activate a custom vars plugins by either dropping it into a ``vars_plugins`` directory adjacent to your play or inside a role
+You can activate a custom vars plugins by either dropping it into a ``vars_plugins`` directory adjacent to your play,  inside a role, or by putting it in one of the directory sources configured in :doc:`ansible.cfg <../config>`.
-or by putting it in one of the directory sources configured in :doc:`ansible.cfg <../config>`.
 
 Plugin Lists
 ++++++++++++
 
-You can use ``ansible-doc -t vars -l`` to see the list of available plugins,
+You can use ``ansible-doc -t vars -l`` to see the list of available plugins. 
-use ``ansible-doc -t vars <plugin name>`` to see specific documents and examples.
+Use ``ansible-doc -t vars <plugin name>`` to see specific plugin-specific documentation and examples.
 
 
 .. toctree:: :maxdepth: 1