realpython · dbader · Nov 23, 2020 · Nov 22, 2020 · Nov 22, 2020 · Nov 22, 2020
diff --git a/docs/index.rst b/docs/index.rst
@@ -4,7 +4,7 @@
    contain the root `toctree` directive.
 
 .. meta::
-   :description: An opinionated guide to the Python programming language and a best practice handbook to the installation, configuration, and usage of Python on a daily basis.
+   :description: An opinionated guide to the Python programming language and a best practice handbook for the installation, configuration, and usage of Python on a daily basis.
 
 
 #################################
@@ -17,15 +17,15 @@ Greetings, Earthling! Welcome to The Hitchhiker's Guide to Python.
 `fork us on GitHub <https://github.com/realpython/python-guide>`_!
 
 This handcrafted guide exists to provide both novice and expert Python
-developers a best practice handbook to the installation, configuration, and
+developers a best practice handbook for the installation, configuration, and
 usage of Python on a daily basis.
 
 This guide is **opinionated** in a way that is almost, but not quite, entirely
 *unlike* Python's official documentation. You won't find a list of every Python web framework
 available here. Rather, you'll find a nice concise list of highly recommended
 options.
 
-.. note:: The use of **Python 3** is *highly* preferred over Python 2. Consider upgrading your applications and infrastructure if you find yourself *still* using Python 2 in production today. If you are using Python 3, congratulations — you are indeed a person of excellent taste.
+.. note:: The use of **Python 3** is *highly* recommended over Python 2. Consider upgrading your applications and infrastructures if you find yourself *still* using Python 2 in production today. If you are using Python 3, congratulations — you are indeed a person of excellent taste.
   —*Kenneth Reitz*
 
 Let's get started! But first, let's make sure you know where your towel is.

diff --git a/docs/scenarios/admin.rst b/docs/scenarios/admin.rst
@@ -199,7 +199,7 @@ Ansible
 *******
 
 `Ansible <http://ansible.com/>`_  is an open source system automation tool.
-The biggest advantage over Puppet or Chef is it does not require an agent on
+Its biggest advantage over Puppet or Chef is that it does not require an agent on
 the client machine. Playbooks are Ansible’s configuration, deployment, and
 orchestration language and are written in YAML with Jinja2 for templating.
 

diff --git a/docs/scenarios/ci.rst b/docs/scenarios/ci.rst
@@ -65,7 +65,7 @@ Travis-CI
 tests for open source projects for free. It provides multiple workers to run
 Python tests on and seamlessly integrates with GitHub. You can even have it
 comment on your Pull Requests whether this particular changeset breaks the
-build or not. So if you are hosting your code on GitHub, Travis-CI is a great
+build or not. So, if you are hosting your code on GitHub, Travis-CI is a great
 and easy way to get started with Continuous Integration.
 
 In order to get started, add a :file:`.travis.yml` file to your repository with

diff --git a/docs/starting/which-python.rst b/docs/starting/which-python.rst
@@ -31,7 +31,7 @@ Recommendations
 ***************
 
 
-.. note:: The use of **Python 3** is *highly* preferred over Python 2. Consider upgrading your applications and infrastructure if you find yourself *still* using Python 2 in production today. If you are using Python 3, congratulations — you are indeed a person of excellent taste.
+.. note:: The use of **Python 3** is *highly* recommended over Python 2. Consider upgrading your applications and infrastructure if you find yourself *still* using Python 2 in production today. If you are using Python 3, congratulations — you are indeed a person of excellent taste.
   —*Kenneth Reitz*
 
 I'll be blunt:

diff --git a/docs/writing/documentation.rst b/docs/writing/documentation.rst
@@ -45,7 +45,7 @@ Project Publication
 Depending on the project, your documentation might include some or all
 of the following components:
 
-- An *introduction* should show a very short overview of what can be
+- An *introduction* should give a very short overview of what can be
   done with the product, using one or two extremely simplified use
   cases. This is the thirty-second pitch for your project.
 
@@ -94,7 +94,7 @@ reStructuredText
 ~~~~~~~~~~~~~~~~
 
 Most Python documentation is written with reStructuredText_. It's like
-Markdown with all the optional extensions built in.
+Markdown, but with all the optional extensions built in.
 
 The `reStructuredText Primer`_ and the `reStructuredText Quick
 Reference`_ should help you familiarize yourself with its syntax.
@@ -149,8 +149,8 @@ a project's documentation.
 Additionally, Doctest_ will read all embedded docstrings that look like input
 from the Python commandline (prefixed with ">>>") and run them, checking to see
 if the output of the command matches the text on the following line. This
-allows developers to  embed real examples and usage of functions alongside
-their source code, and as a side effect, it also ensures that their code is
+allows developers to embed real examples and usage of functions alongside
+their source code. As a side effect, it also ensures that their code is
 tested and works.
 
 ::
@@ -187,8 +187,8 @@ Docstrings are accessible from both the `__doc__` dunder attribute for almost
 every Python object, as well as with the built in `help()` function.
 
 While block comments are usually used to explain *what* a section of code is
-doing, or the specifics of an algorithm, docstrings are more intended for
-explaining to other users of your code (or you in 6 months time) *how* a
+doing, or the specifics of an algorithm, docstrings are more intended towards
+explaining other users of your code (or you in 6 months time) *how* a
 particular function can be used and the general purpose of a function, class,
 or module.
 
@@ -214,7 +214,7 @@ In larger or more complex projects however, it is often a good idea to give
 more information about a function, what it does, any exceptions it may raise,
 what it returns, or relevant details about the parameters.
 
-For more detailed documentation of code a popular style is the one used for the
+For more detailed documentation of code a popular style used, is the one used by the
 NumPy project, often called `NumPy style`_ docstrings. While it can take up more
 lines than the previous example, it allows the developer to include a lot
 more information about a method, function, or class. ::

diff --git a/docs/writing/gotchas.rst b/docs/writing/gotchas.rst
@@ -7,13 +7,13 @@ Common Gotchas
 .. image:: /_static/photos/34435688380_b5a740762b_k_d.jpg
 
 For the most part, Python aims to be a clean and consistent language that
-avoids surprises. However, there are a few cases that can be confusing to
+avoids surprises. However, there are a few cases that can be confusing for
 newcomers.
 
 Some of these cases are intentional but can be potentially surprising. Some
 could arguably be considered language warts. In general, what follows
 is a collection of potentially tricky behavior that might seem strange at first
-glance, but is generally sensible once you're aware of the underlying cause for
+glance, but are generally sensible, once you're aware of the underlying cause for
 the surprise.
 
 
@@ -53,8 +53,8 @@ isn't provided, so that the output is::
     [12]
     [42]
 
-What Does Happen
-~~~~~~~~~~~~~~~~
+What Actually Happens
+~~~~~~~~~~~~~~~~~~~~~
 
 .. testoutput::
 
@@ -100,6 +100,7 @@ Late Binding Closures
 Another common source of confusion is the way Python binds its variables in
 closures (or in the surrounding global scope).
 
+
 What You Wrote
 ~~~~~~~~~~~~~~
 
@@ -125,8 +126,8 @@ variable that multiplies their argument, producing::
     6
     8
 
-What Does Happen
-~~~~~~~~~~~~~~~~
+What Actually Happens
+~~~~~~~~~~~~~~~~~~~~~
 
 .. testoutput::
 
@@ -206,7 +207,7 @@ will automatically write a bytecode version of that file to disk, e.g.
 These ``.pyc`` files should not be checked into your source code repositories.
 
 Theoretically, this behavior is on by default for performance reasons.
-Without these bytecode files present, Python would re-generate the bytecode
+Without these bytecode files, Python would re-generate the bytecode
 every time the file is loaded.
 
 

diff --git a/docs/writing/license.rst b/docs/writing/license.rst
@@ -6,8 +6,8 @@ Choosing a License
 
 .. image:: /_static/photos/33907149294_82d7535a6c_k_d.jpg
 
-Your source publication *needs* a license. In the US, if no license is
-specified, users have no legal right to download, modify, or distribute.
+Your source publication *needs* a license. In the US, unless a license is
+specified, users have no legal right to download, modify, or distribute the product.
 Furthermore, people can't contribute to your code unless you tell them what
 rules to play by. Choosing a license is complicated, so here are some pointers:
 

diff --git a/docs/writing/logging.rst b/docs/writing/logging.rst
@@ -10,7 +10,7 @@ The :mod:`logging` module has been a part of Python's Standard Library since
 version 2.3.  It is succinctly described in :pep:`282`.  The documentation
 is notoriously hard to read, except for the `basic logging tutorial`_.
 
-As an alternative, `loguru <https://github.com/Delgan/loguru>`_ provides an approach to logging nearly as simple as using a simple ``print`` statement.
+As an alternative, `loguru <https://github.com/Delgan/loguru>`_ provides an approach for logging, nearly as simple as using a simple ``print`` statement.
 
 Logging serves two purposes:
 
@@ -59,7 +59,7 @@ using the ``__name__`` global variable: the :mod:`logging` module creates a
 hierarchy of loggers using dot notation, so using ``__name__`` ensures
 no name collisions.
 
-Here is an example of best practice from the `requests source`_ -- place
+Here is an example of the best practice from the `requests source`_ -- place
 this in your ``__init__.py``:
 
 .. code-block:: python
@@ -83,7 +83,7 @@ application environment.
 There are at least three ways to configure a logger:
 
 - Using an INI-formatted file:
-    - **Pro**: possible to update configuration while running using the
+    - **Pro**: possible to update configuration while running, using the
       function :func:`logging.config.listen` to listen on a socket.
     - **Con**: less control (e.g. custom subclassed filters or loggers)
       than possible when configuring a logger in code.
@@ -94,13 +94,13 @@ There are at least three ways to configure a logger:
     - **Con**: less control than when configuring a logger in code.
 - Using code:
     - **Pro**: complete control over the configuration.
-    - **Con**: modifications require a change to source code.
+    - **Con**: modifications require a change to the source code.
 
 
 Example Configuration via an INI File
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Let us say the file is named ``logging_config.ini``.
+Let us say that the file is named ``logging_config.ini``.
 More details for the file format are in the `logging configuration`_
 section of the `logging tutorial`_.