Improve readme and contributing guide sections further with reviewer feedback

Co-authored-by: Hugo van Kemenade <[email protected]>

Author: CAM-Gerlach

.github/CODEOWNERS

@@ -24,9 +24,11 @@ contents.rst            @AA-Turner
 generate_rss.py         @AA-Turner
 
 # Linting infrastructure
-.codespell/             @CAM-Gerlach
-.codespellrc            @CAM-Gerlach
-.pre-commit-config.yaml @CAM-Gerlach
+.codespell/             @CAM-Gerlach @hugovk
+.codespellrc            @CAM-Gerlach @hugovk
+.pre-commit-config.yaml @CAM-Gerlach @hugovk
+
+# Git infrastructure
 .gitattributes          @CAM-Gerlach
 .gitignore              @CAM-Gerlach
 

CONTRIBUTING.rst

@@ -56,8 +56,8 @@ position within the project.
 Run pre-commit linting locally
 ------------------------------
 
-If you'd like, you can run the project's basic linting suite locally,
-either on-demand when you choose, or automatically against modified files
+You can run this repo's basic linting suite locally,
+either on-demand, or automatically against modified files
 whenever you commit your changes.
 
 They are also run in CI, so you don't have to run them locally, though doing
@@ -69,12 +69,12 @@ install, configure and update a suite of hooks that check for
 common problems and issues, and fix many of them automatically.
 
 If your system has ``make`` installed, you can run the pre-commit checkers
-on the full repo by simply running ``make lint``. Note that this will
+on the full repo by running ``make lint``. This will
 install pre-commit in the current virtual environment if it isn't already,
 so make sure you've activated the environment you want it to use
 before running this command.
 
-Otherwise, you can install pre-commit by running ``pip install pre-commit``
+Otherwise, you can install pre-commit by running ``python -m pip install pre-commit``
 (or your choice of installer), and then run the hooks on all the files
 in the repo with ``pre-commit run --all-files``, or only on any files that
 have been modified but not yet committed with ``pre-commit run``.
@@ -97,7 +97,7 @@ Like the linters, on a system with ``make`` available, it can be installed
 repository with a single command, ``make spellcheck``.
 
 For finer control or on other systems, after installing pre-commit as above
-(e.g. ``pip install pre-commit``), you can run it against only the files
+(e.g. ``python -m pip install pre-commit``), you can run it against only the files
 you've modified and not yet committed with
 ``pre-commit run --hook-stage manual codespell``, or against all files with
 ``pre-commit run --all-files --hook-stage manual codespell``.

README.rst

@@ -43,13 +43,13 @@ libraries in the ``pep0`` directory.
 Checking PEP formatting and rendering
 =====================================
 
-Avoid committing changes with reStructuredText syntax errors that cause PEP
-generation to fail, or result in major rendering defects relative to what
-you intend. To build the HTML output for your PEP (for example, PEP 12)
+Please don't commit changes with reStructuredText syntax errors that cause PEP
+generation to fail, or result in major rendering defects relative to what you
+intend. To check building the HTML output for your PEP (for example, PEP 12)
 using the current default docutils-based system, run the ``pep2html.py`` script
-with your PEP source file as its argument, e.g. for PEP 12,
-``python -X dev pep2html.py pep-0012.rst``,
-If you're on a system with ``make``, you can instead simply execute, e.g.,
+with your PEP source file as its argument (e.g. for PEP 12,
+``python pep2html.py pep-0012.rst``).
+If you're on a system with ``make``, you can instead execute, e.g.,
 ``make pep-0012.rst``.
 To generate HTML for all the PEPs, run the script/``make`` without a PEP
 file argument.