Apply suggestions from code review

Co-authored-by: Abhijeet Kasurde <[email protected]>

Author: bcoca

docs/docsite/rst/dev_guide/developing_collections_documenting.rst

@@ -7,7 +7,7 @@ Documenting collections
 Documenting modules and plugins
 ===============================
 
-Documenting modules is thoroughly documented in :ref:`module_documenting`. Plugins can be documented in a similar way to modules :ref:`plugins_documenting`, that is with ``DOCUMENTATION``, ``EXAMPLES``, and ``RETURN`` blocks.
+A comprehensive guide to documenting modules can be found in :ref:`module_documenting`. Plugins can be documented similarly to modules :ref:`plugins_documenting`, that is with ``DOCUMENTATION``, ``EXAMPLES``, and ``RETURN`` blocks.
 
 Documenting roles
 =================

docs/docsite/rst/dev_guide/plugins_documenting.rst

@@ -4,7 +4,7 @@
 Plugin format and documentation
 *******************************
 
-Not all plugins can be documented, but those that can (`documentable <https://github.com/ansible/ansible/blob/devel/lib/ansible/constants.py#L111>`), follow a specific common format, except modules that have their own extended format. Also some of these plugin types (`configurable <https://github.com/ansible/ansible/blob/devel/lib/ansible/constants.py#L109>`) use the documentation to build their argument validation and type casting, unlike modules that require a separate 'args_spec'.
+Not all plugins can be documented, but those that can (`documentable <https://github.com/ansible/ansible/blob/devel/lib/ansible/constants.py#L111>`), follow a specific common format, except modules that have their own extended format. Also, some of these plugin types (`configurable <https://github.com/ansible/ansible/blob/devel/lib/ansible/constants.py#L109>`) use the documentation to build their argument validation and type casting, unlike modules that require a separate 'args_spec'.
 
 This document will describe how the plugin configuration works in general, excluding modules, which have their own `documentation reference:developing_modules_documenting`.
 
@@ -20,15 +20,15 @@ Every Ansible plugin must be written in Python, with modules being the main exce
 
 .. note:: Why don't the imports go first?
 
-  Keen Python programmers may notice that contrary to PEP 8's advice we don't put ``imports`` at the top of the file. This is because the ``DOCUMENTATION`` through ``RETURN`` sections are essentially extra docstrings for the file. The imports are placed after these special variables for the same reason as PEP 8 puts the imports after the introductory comments and docstrings. This keeps the active parts of the code together and the pieces which are purely informational apart. The decision to exclude E402 is based on readability (which is what PEP 8 is about). Documentation strings in a plugin are much more similar to module level docstrings. Placing the imports below this documentation and closer to the code, consolidates and groups all related code in a congruent manner to improve readability, debugging and understanding.
+  Keen Python programmers may notice that contrary to PEP 8's advice we don't put ``imports`` at the top of the file. This is because the ``DOCUMENTATION`` through ``RETURN`` sections are essentially extra docstrings for the file. The imports are placed after these special variables for the same reason as PEP 8 puts the imports after the introductory comments and docstrings. This keeps the active parts of the code together and the pieces which are purely informational apart. The decision to exclude E402 is based on readability (which is what PEP 8 is about). Documentation strings in a plugin are much more similar to module-level docstrings. Placing the imports below this documentation and closer to the code, consolidates and groups all related code in a congruent manner to improve readability, debugging and understanding.
 
 
 .. _plugins_shebang_and_encoding:
 
 Python shebang & UTF-8 coding
 ===============================
 
-Plugins in general won't use a shebang as they are imported into Ansible's engine and not executed as a script (unlike modules).
+Unlike modules, shebangs are not used by plugins since they are imported into Ansible's engine rather than being run as a script.
 So your first line will normally be the encoding::
 
     # -*- coding: utf-8 -*-
@@ -57,9 +57,9 @@ Please do not include a copyright year. If the existing copyright statement incl
 DOCUMENTATION block
 ===================
 
-The 3rd section is the ``DOCUMENTATION`` block. Ansible's plugin documentation is generated from the ``DOCUMENTATION`` blocks, both for the online site and the ``ansible-doc`` output. The ``DOCUMENTATION`` block must be valid YAML. You may find it easier to start writing your ``DOCUMENTATION`` string in an :ref:`editor with YAML syntax highlighting <other_tools_and_programs>` before you include it in your Python file.
+The next section is the ``DOCUMENTATION`` block. Ansible's plugin documentation is generated from the ``DOCUMENTATION`` blocks, both for the online site and the ``ansible-doc`` output. The ``DOCUMENTATION`` block must be valid YAML. You may find it easier to start writing your ``DOCUMENTATION`` string in an :ref:`editor with YAML syntax highlighting <other_tools_and_programs>` before you include it in your Python file.
 
-Plugin documentation should briefly and accurately define what each plugin is meant to accomplish and what and each option does. Documentation should be written for broad audience--readable both by experts and non-experts.
+Plugin documentation should briefly and accurately define what each plugin is meant to accomplish and what and each option does. Documentation should be written for a broad audience--readable both by experts and non-experts.
     * Descriptions should always start with a capital letter and end with a full stop. Consistency always helps.
 
 To create clear, concise, consistent, and useful documentation, follow the :ref:`style guide <style_guide>`.
@@ -91,9 +91,9 @@ All fields in the ``DOCUMENTATION`` block are lower-case. All fields are require
 
   * A detailed description (generally two or more sentences).
   * Must be written in full sentences, in other words, with capital letters and periods/full stops.
-  * Shouldn't mention the plugin name.
+  * Should not mention the plugin name.
   * Make use of multiple entries rather than using one long paragraph.
-  * Don't quote complete values unless it is required by YAML.
+  * Do not quote complete values unless it is required by YAML.
 
 :version_added:
 
@@ -104,7 +104,7 @@ All fields in the ``DOCUMENTATION`` block are lower-case. All fields are require
 
   * Name of the author in the form ``First Last (@GitHubID)``.
   * Use a multi-line list if there is more than one author.
-  * Don't use quotes as it should not be required by YAML.
+  * Do not use quotes as it should not be required by YAML.
 
 :deprecated: