PR review fixes

Author: Chris Cho

snooty.toml

@@ -10,7 +10,7 @@ package-branch = "testing"
 package-version = "4.4.0"
 package-name-org = "mongodb-org"
 version = "4.0"
-rst-title = "ReStructuredText"
+rst-title = "reStructuredText"
 rst = "reStructuredText"
 rst-abbrev = "RST"
 yaml = "Yet Another Markup Language"

source/style-guide/markup/directives/code-blocks.txt

@@ -3,15 +3,15 @@ Code Examples
 =============
 
 As needed, use the appropriate language option for code blocks directives
-including the following:
+including the following directives:
 
 - ``code-block``
 - ``io-code-block``
 - ``literalinclude``
 
-This enables syntax highlighting which makes the source code easier to
-interpret. The following example shows how to specify Python language
-syntax highlighting in a ``code-block`` directive:
+These directives feature syntax highlighting which makes the source code 
+contained in them easier to interpret. The following example shows how to 
+specify Python language syntax highlighting in a ``code-block`` directive:
 
 .. code-block::
 

source/style-guide/markup/directives/tables.txt

@@ -4,10 +4,10 @@ Table Directives
 
 Use tables to format related information.
 
-In Snooty, you can only use the ``list-table`` directive to build tables.
+In Snooty, you can use only the ``list-table`` directive to build tables.
 The ``list-table`` directive generates a formatted table from a two-level
-bullet list.
+bulleted list.
 
-Learn more about the ``list-table`` directive frmo the
+To learn more about the ``list-table`` directive from the
 `{+docutils+} documentation </directives#list-table>`__.
 

source/style-guide/markup/directives/tabs.txt

@@ -85,9 +85,8 @@ all pages that use the same tab set:
 - Eliminate the need for the writer to specify the tab display name
   (tab label)
 
-Refer to the `Snooty configuration file <https://github.com/mongodb/snooty-parser/blob/master/snooty/rstspec.toml>`__
- to find the pre-defined tab sets. Each of the entries starts with
-``[directive.tabs-``.
+To find the pre-defined tab sets, see the `Snooty configuration file <https://github.com/mongodb/snooty-parser/blob/master/snooty/rstspec.toml>`__.
+Each entry starts with ``[directive.tabs-``.
 
 Pre-defined tab sets require the following fields for each tab:
 
@@ -149,8 +148,8 @@ code examples stored in different files:
 Defining a New Tab Set
 ~~~~~~~~~~~~~~~~~~~~~~
 
-Reach out to the {+docs-platform+} for more information on creating a new
-pre-defined tab set. 
+To learn more about creating a new pre-defined tab set, contact the
+{+docs-platform+}.
 
 Using a Custom Tab Set
 ~~~~~~~~~~~~~~~~~~~~~~

source/style-guide/markup/format/lists.txt

@@ -5,7 +5,8 @@ Lists
 Lists are body elements that organize information into adjacent blocks of
 markup. Each level of a list must start and end with a blank line.
 
-Learn more about when to use lists from the :ref:`<lists>` style guide entry.
+To learn more about when to use lists, see the :ref:`<lists>` style guide
+entry.
 
 Unordered Lists
 ~~~~~~~~~~~~~~~
@@ -102,8 +103,8 @@ Ordered lists append a number before each item to show a sequential order.
 Definition Lists
 ~~~~~~~~~~~~~~~~
 
-Definition lists specify a term and a related block that can be used to
+Definition lists specify a term and a related block that you can use to
 describe the term.
 
-Learn more about definition lists from the `{+docutils+} documentation <http://www.docutils.org/docs/ref/rst/restructuredtext.html#definition-lists>`__.
+To learn more about definition lists, see the `{+docutils+} documentation <http://www.docutils.org/docs/ref/rst/restructuredtext.html#definition-lists>`__.
 

source/style-guide/markup/format/roles.txt

@@ -2,11 +2,10 @@
 Roles
 =====
 
-Roles are a type of directive that are used inline and can be used to create
-cross-references or apply formatting. Use them consistently to ensure
-uniform formatting.
+Roles are inline directives used to create cross-references or apply formatting.
+Use them consistently to ensure uniform formatting.
 
-Learn more about roles from the
+To learn more about roles, see the
 `Sphinx documentation <https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html>`__.
 
    .. toctree::

source/style-guide/markup/format/substitutions.txt

@@ -2,13 +2,19 @@
 Substitutions
 =============
 
+In Snooty, you can use variables to represent a text value in the
+rendered form of the documentation. These variables are called
+source constants. When used consistently, they help prevent inconsistencies in
+formatting the term and make it easy to change the value for all its
+occurrences.
+
 Source Constants
 ----------------
 
 Source constants define substitution text for variables in {+rst+} files.
 When building the documentation, the substitution text replaces the instances
 of the variables prior to {+docutils+} parser transforming the document to
-HTML. Source constants can be used within directives and roles.
+HTML. You can use source constants within directives and roles.
 
 You can add or modify source constants in your documentation repository's
 ``snooty.toml`` file in the base directory. Source constants should be
@@ -24,7 +30,7 @@ include the following line in the ``[constants]`` section:
 
    mdn = "https://developer.mozilla.org/en-US/docs/MDN/"
 
-To use the source constant, as shown in the following example:
+Use the source constant as shown in the following example:
 
 .. code-block:: rst
 
@@ -33,7 +39,7 @@ To use the source constant, as shown in the following example:
 
 .. important::
 
-   In your {+rst+}, source constants should not contain spaces between curly
+   In your {+rst+}, source constants shouldn't contain spaces between curly
    braces and plus signs as shown in the example. The spaces were
    intentionally added to the example to prevent the parser from substituting
    a value.

source/style-guide/markup/headings.txt

@@ -5,7 +5,7 @@ Headings and Sections
 Headings organize information into a hierarchy of sections.
 To set headings, add repeating characters below the heading text.
 
-Learn more about headings from the
+To learn more about headings, see the
 `Sphinx documentation <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#sections>`__.
 
 Heading Markup Rules
@@ -48,7 +48,7 @@ To avoid errors in your header markup syntax, stick to the following rules:
             ~~~~~~~~~~~~~~~~~~~
 
 - Make the underline as long as the text above it. If you use a source constant
-  in the header, you need the line to match the length of the resolved text.
+  in the header, the underline must match the length of the resolved text.
 
   .. list-table::
      :header-rows: 1

source/style-guide/markup/inline.txt

@@ -11,17 +11,17 @@ Inline Markup
 Inline markup, also known as roles, specify how the enclosed text should be
 interpreted or rendered.
 
-Learn more about roles from the `{+docutils+} documentation <http://www.docutils.org/docs/ref/rst/roles.html>`__.
+To learn more about roles, see the `{+docutils+} documentation <http://www.docutils.org/docs/ref/rst/roles.html>`__.
 
-{+sphinx+} provides an extended set of roles. Learn more about these roles
-from the `Sphinx documentation <https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html>`__.
+{+sphinx+} provides an extended set of roles. To learn more about the
+extended roles, see the `Sphinx documentation <https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html>`__.
 
 Font Formatting Roles
 ---------------------
 
-These roles control how the font of the enclosed text is rendered.
+These roles control how the font of the enclosed text renders.
 
-Learn more about when to use these roles from the style guide section on
+To learn more about when to use these roles, see the style guide section on
 :ref:`<text-formatting>`.
 
 - To **strongly emphasize** or **bold** text, use two asterisks on
@@ -91,7 +91,7 @@ Use the following guidelines to avoid errors in font formatting roles:
 
             **``bold code``**
 
-- When applying a text formatting role to the middle of a word, use a backslash
+- When you apply a text formatting role to the middle of a word, use a backslash
   and space character on both sides of the formatted text.
 
   .. list-table::