docs: Various grammar / syntax improvements

docs/api/operations.md

@@ -1,10 +1,10 @@
 # Writing Facts & Operations
 
-Operations & facts the building blocks pyinfra uses to make changes to hosts, this document describes how you can write your own to extend pyinfra's functionality.
+Operations & facts are the building blocks pyinfra uses to make changes to hosts. This document describes how you can write your own to extend pyinfra's functionality.
 
 ## Operations
 
-[Operations](../operations) are defined as Python functions. They are passed the current deploy state, the target host and any operation arguments. Operation functions read state from the host, comparing it to the arguments, and yield commands.
+[Operations](../operations) are defined as Python functions. They are passed the current deploy state, the target host, and any operation arguments. Operation functions read state from the host, compare it to the arguments, and yield commands.
 
 ### Input: arguments
 
@@ -88,7 +88,7 @@ passed (as a ``list`` of lines) to the ``process`` handler to generate fact data
 
 Fact classes may provide a ``default`` function that takes no arguments (except ``self``). The return value of this function is used if an error
 occurs during fact collection. Additionally, a ``requires_command`` variable can be set on the fact that specifies a command that must be available
-on the host to collect the fact. If this command is not present on the host the fact will be set to the default, or empty if no ``default`` function
+on the host to collect the fact. If this command is not present on the host, the fact will be set to the default, or empty if no ``default`` function
 is available.
 
 ### Importing & Using Facts

docs/api/reference.rst

@@ -3,11 +3,11 @@ API Reference
 
 The pyinfra API is designed to be used as follows:
 
-1. Create the state we are going to operate on, this consists of:
+1. Create the state we are going to operate on, which consists of:
     - An inventory ``pyinfra.api.Inventory`` containing hosts ``pyinfra.api.Host``, plus any data
     - A config ``pyinfra.api.Config`` for global flag
     - A state ``pyinfra.api.State`` that combines the inventory & config
-2. Now state is setup, we define operations:
+2. Now that state is setup, we define operations:
     - ``pyinfra.api.operation.add_op``
     - ``pyinfra.api.add_deploy``
 3. Now that's done, we execute it:

docs/facts.rst

@@ -1,7 +1,7 @@
 Facts Index
 ===========
 
-pyinfra uses **facts** to determine the existing state of a remote server. Operations use this information to generate commands which alter the state. Facts are read-only and is populated at the beginning of the deploy.
+pyinfra uses **facts** to determine the existing state of a remote server. Operations use this information to generate commands which alter the state. Facts are read-only and are populated at the beginning of the deploy.
 
 Facts can be executed/tested via the command line:
 
@@ -23,7 +23,7 @@ Multiple facts with arguments may be called like so:
 
     pyinfra @local fact files.File path=setup.py files.File path=anotherfile.txt
 
-You can leverage facts as part of :doc:`within operations <using-operations>` like this:
+You can leverage facts within :doc:`operations <using-operations>` like this:
 
 .. code:: py
 

docs/inventory-data.rst

@@ -1,9 +1,9 @@
 Inventory & Data
 ================
 
-A pyinfra inventory provides hosts, groups and data. Host are the things pyinfra will make changes to (think a SSH daemon on a server, a Docker container or the local machine). Hosts can be attached to groups, and data can then be assigned to both the groups and individual hosts.
+A pyinfra inventory provides hosts, groups and data. Hosts are the things pyinfra will make changes to (think a SSH daemon on a server, a Docker container or the local machine). Hosts can be attached to groups, and data can then be assigned to both the groups and individual hosts.
 
-By default pyinfra assumes hosts are SSH servers and the name of the host is used as the SSH hostname. Prefixing the name of the host with ``@<connector-name>/`` is used to activate alternative connectors. See: :doc:`connectors`.
+By default, pyinfra assumes hosts are SSH servers and the name of the host is used as the SSH hostname. Prefixing the name of the host with ``@<connector-name>/`` is used to activate alternative connectors. See: :doc:`connectors`.
 
 Inventory Files
 ---------------
@@ -63,7 +63,7 @@ Data can be assigned to individual hosts in the inventory by using a tuple ``(ho
         ("db-1.net", {"install_postgres": True}),
     ]
 
-This can then be used in operations files:
+This data can then be used in operations:
 
 .. code:: python
 
@@ -84,7 +84,7 @@ Group data can be stored in separate files under the ``group_data`` directory (t
     app_user = "myuser"
     app_dir = "/opt/pyinfra"
 
-These can then be used in operations:
+These variables can then be used in operations:
 
 .. code:: python
 
@@ -115,7 +115,7 @@ The same keys can be defined for host and group data - this means we can set a d
 Connecting with Data
 --------------------
 
-Data can be used to configure connectors, for example setting SSH connection details can be done like so:
+Data can be used to configure connectors. For example, setting SSH connection details can be done like so:
 
 .. code:: python
 

docs/using-operations.rst

@@ -152,7 +152,7 @@ All operations return an operation meta object which provides information about
 Operation Output
 ~~~~~~~~~~~~~~~~
 
-pyinfra doesn't immediately execute operations meaning output is not available right away. It is possible to access this output at runtime by providing a callback function using the :ref:`operations:python.call` operation.
+pyinfra doesn't immediately execute operations, meaning output is not available right away. It is possible to access this output at runtime by providing a callback function using the :ref:`operations:python.call` operation.
 
 .. code:: python
 
@@ -216,7 +216,7 @@ See more in :doc:`examples: groups & roles <./examples/groups_roles>`.
 The ``config`` Object
 ---------------------
 
-Like ``host`` and ``inventory``, ``config`` can be used to set global defaults for operations. For example, to use sudo in all operations following:
+Like ``host`` and ``inventory``, ``config`` can be used to set global defaults for operations. For example, to use sudo in all following operations:
 
 .. code:: python