Merge pull request #126 from davemungo/DOCS-14189-issues-in-writing-guidlines

DOCS-14189 issues in writing guidlines

Author: Chris Cho

source/style-guide/style/capitalization.txt

@@ -7,7 +7,8 @@ Capitalization
 .. default-domain:: mongodb
 
 Be judicious and consistent in your use of capitalization. This topic
-provides general guidelines to help you decide to capitalize a term.
+provides general guidelines to help you decide when to capitalize a
+term.
 
 .. seealso::
 
@@ -177,17 +178,17 @@ an incorrect capitalization:
      - ftp
          Command-line FTP client
    * - KBps
-         kilobytes per second
+         Kilobytes per second
      - Kbps
-         kilobits per second
+         Kilobits per second
    * - May
          Fifth month of the year
      - may
-         modal verb
+         Modal verb
    * - REST
          Representational State Transfer
      - rest
-         State of motionless or inactivity
+         State of motionlessness or inactivity
 
 Capitalize Team Names
 ---------------------
@@ -203,8 +204,6 @@ shown in the following table:
 
    * - The Support team handles making the change for you.
 
-   * - The Support team handles making the change for you.
-
    * - Contact your Account Management team can tell you what the
        charge will be.
 
@@ -253,8 +252,8 @@ object in a product is a proper noun.
 
    - Atlas enables users to create a *cluster*, not a *Cluster*.
 
-   - When the user creates a cluster, the user specifies an *cloud
-     provider*, *tier*, and *region*, not an *Cloud Provider*, *Tier*,
+   - When the user creates a cluster, the user specifies a *cloud
+     provider*, *tier*, and *region*, not a *Cloud Provider*, *Tier*,
      and *Region*.
 
    - A user can create a *load balancer*, not a *Load Balancer*.

source/style-guide/style/code-examples.txt

@@ -4,13 +4,6 @@
 Code Examples
 =============
 
-.. include:: /style-guide/includes/page-needs-update.rst
-
-.. note::
-
-   For more information about formatting code, see the "Code" row in
-   the Text formatting topic.
-
 Use the following guidelines when creating blocks of code as input
 or output examples:
 
@@ -109,7 +102,7 @@ Create a VM Running a Docker Host
       NAME ACTIVE DRIVER STATE URL SWARM
       test virtualbox Running tcp://192.168.99.101:237
 
-Run the application
+Run the Application
 -------------------
 
 #. Run a container from the image. The application code uses the

source/style-guide/style/placeholder-variable-text.txt

@@ -8,15 +8,15 @@ Placeholder or Variable Text
 
 Use placeholder text for a value when you:
 
-- don't know its specific value
-- don't or shouldn't use an example value
+- Don't know its specific value
+- Don't or shouldn't use an example value
 
 Use placeholders when demonstrating how a command or path should be
 constructed. Users supply the relevant value for the placeholder when
 using the command or syntax. When using placeholders, instruct users to
 replace the placeholders with the relevant values.
 
-Placeholder text can also referred to as *variable text* or
+Placeholder text is also referred to as *variable text* or
 *replaceable text*.
 
 Placeholder text usually indicates the type of element that's being

source/style-guide/style/punctuation.txt

@@ -8,8 +8,9 @@ Punctuation
 
 Use punctuation correctly and consistently. This section provides
 guidelines for using punctuation in MongoDB documentation. For basic
-rules about punctuation, see :`section 5, Grammar and Usage
-<https://www.chicagomanualofstyle.org/book/ed17/part2/ch05/toc.html>`__ in the *Chicago Manual of Style*.
+rules about punctuation, see `section 5, Grammar and Usage
+<https://www.chicagomanualofstyle.org/book/ed17/part2/ch05/toc.html>`__
+in the *Chicago Manual of Style*.
 
 .. contents:: On this page
    :local:
@@ -62,9 +63,10 @@ Use the following guidelines for colons:
 Commas
 ~~~~~~
 
-Use the following guidelines for commas. For basic comma usage,
-`section 6.16, Commas <https://www.chicagomanualofstyle.org/book/ed17/part2/ch06/psec016.html>`__ in the Chicago
-Manual of Style.
+Use the following guidelines for commas. For basic comma usage, see
+`section 6.16, Commas
+<https://www.chicagomanualofstyle.org/book/ed17/part2/ch06/psec016.html>`__
+in the *Chicago Manual of Style*.
 
 .. list-table::
    :widths: 40 30 30
@@ -299,7 +301,8 @@ be necessary in the following cases:
 
 For the correct formatting of a specific word, see a dictionary or
 :ref:`alphabetical-list-of-terms`. For more information about
-hyphenating prefixes, see *The Chicago Manual of Style*.
+hyphenating prefixes, see `The Chicago Manual of Style
+<https://www.chicagomanualofstyle.org/qanda/data/faq/topics/HyphensEnDashesEmDashes/faq0079.html>`__.
 
 Parentheses
 ~~~~~~~~~~~
@@ -347,7 +350,9 @@ Periods
 ~~~~~~~
 
 Use the following guidelines for periods. For basic period usage, see a
-grammar reference, `section 6.12, Periods <https://www.chicagomanualofstyle.org/book/ed17/part2/ch06/psec012.html>`__ in the *Chicago Manual of Style*.
+grammar reference, `section 6.12, Periods
+<https://www.chicagomanualofstyle.org/book/ed17/part2/ch06/psec012.html>`__
+in the *Chicago Manual of Style*.
 
 - Use a period at the end of a declarative or imperative sentence, and
   insert only one space after the period.

source/style-guide/style/tasks.txt

@@ -93,7 +93,7 @@ steps. You could include the following information:
 Procedures
 ~~~~~~~~~~
 
-A task contains one or more *procedures*, or set of sequential action
+A task contains one or more *procedures* or sets of sequential action
 steps. Consider the following guidelines when creating a procedure:
 
 -  If the procedure has more than one step, use a ``steps`` file for
@@ -156,7 +156,7 @@ the menu, you can include both actions in one step.
 
    #. If you're prompted to save your file, save it to your computer.
 
-Provide context before the action
+Provide Context Before the Action
 `````````````````````````````````
 
 If a step specifies where to perform an action, state where to perform
@@ -169,8 +169,8 @@ the action before describing the action.
    #. On the Binding and SSL Settings page, perform the following
       steps:
 
-Provide conditions before actions
-`````````````````````````````````
+Provide Conditions Before the Action
+````````````````````````````````````
 
 If a step specifies a situation or a condition, state the situation or
 condition before describing the action.

source/style-guide/style/text-formatting.txt

@@ -10,13 +10,6 @@ You should add formatting to words, phrases, or blocks that require
 emphasis. You can use one of the formatting options to convey emphasis:
 weight (**bold**), variant (*italics*), or pitch (``monospace``).
 
-.. note::
-
-   Characters in a *monospace*, *fixed-pitch* or *fixed-width* font
-   occupy the same amount of horizontal space. In MongoDB
-   documentation, we use the monospace font *Source Code Pro*. This
-   font looks as follows: ``monospace font``
-
 When formatting text, use the following guidelines:
 
 -  To apply a font treatment, use the appropriate markup in your
@@ -124,7 +117,7 @@ elements. The following style differences are highlighted:
 
    Box names
      This covers check box, combo box, group box, list box, spin box,
-     text box, but not dialog box. Format using ``:guilabel:`` role.
+     and text box. Format them using the ``:guilabel:`` role.
 
      .. class:: exampletable
 
@@ -518,12 +511,12 @@ elements. The following style differences are highlighted:
                :copyable: false
 
                The following example shows a basic configuration for
-               the FTP service, in a file in the ``/etc/xinetd.d
-               directory``.
+               the FTP service, in a file in the ``/etc/xinetd.d/``
+               directory.
 
         * - Rendered Example
           - The following example shows a basic configuration for the
-            FTP service, in a file in the ``/etc/xinetd.d directory``.
+            FTP service, in a file in the ``/etc/xinetd.d/`` directory.
 
    Document titles
      Format using *italics*.
@@ -645,7 +638,8 @@ elements. The following style differences are highlighted:
 
         * - Linux, macOS
           - Format using ``monospace`` text and uppercase letters.
-            Start with ``$`` when getting, omit the ``$`` when assigning.
+            Start with ``$`` when getting, omit the ``$`` when
+            assigning.
           -
             .. code-block:: console
 
@@ -654,7 +648,8 @@ elements. The following style differences are highlighted:
                echo $HOME
         * - DOS, Windows Command-Line Interpreter
           - Format using ``monospace`` text and uppercase letters.
-            Start and end with ``%`` when getting, omit the ``%`` when assigning.
+            Start and end with ``%`` when getting, omit the ``%`` when
+            assigning.
           -
             .. code-block:: doscon
 
@@ -764,35 +759,35 @@ elements. The following style differences are highlighted:
                   :copyable: false
 
                   db.collection.create_index(
-                      [
-                        (<keyAndIndexTypeSpecification>
-                      ], <options>
-                    )
+                    [
+                      (<keyAndIndexTypeSpecification>
+                    ], <options>
+                  )
 
                .. code-block:: java
                   :copyable: false
 
                   collection.createIndex(
                     <keyAndIndexTypeSpecification>, <options>
-                    )
+                  )
 
         * - Rendered Example
           -
             .. code-block:: javascript
                :copyable: false
 
                db.collection.create_index(
-                   [
-                     (<keyAndIndexTypeSpecification>)
-                   ], <options>
-                 )
+                 [
+                   (<keyAndIndexTypeSpecification>)
+                 ], <options>
+               )
 
             .. code-block:: java
                :copyable: false
 
                collection.createIndex(
                  <keyAndIndexTypeSpecification>, <options>
-                 )
+               )
 
    Field names, GUI
      Format using ``:guilabel:`` role.
@@ -1182,31 +1177,6 @@ elements. The following style differences are highlighted:
           - Client authentication is provided through a REST interface
             by using the ``GET`` method.
 
-   New terms
-     Format using *italics*.
-
-     .. class:: exampletable
-
-     .. list-table::
-        :widths: 25 75
-        :stub-columns: 1
-
-        * - Code Example
-          -
-            .. code-block:: rst
-               :copyable: false
-
-               Clusters that are built using the base Linux images are
-               created without a dedicated swap partition and with
-               *swappiness* (a measure of how the Linux kernel tries to
-               use swap memory) set to 0.
-
-        * - Rendered Example
-          - Clusters that are built using the base Linux images are
-            created without a dedicated swap partition and with
-            *swappiness* (a measure of how the Linux kernel tries to
-            use swap memory) set to 0.
-
    Option names, command
      Format using ``:option:`` role.
 
@@ -1413,6 +1383,8 @@ elements. The following style differences are highlighted:
                firewall changes as a normal user with ``sudo``
                privileges.
 
+               The user is granted ALL privileges on the database.
+
         * - Rendered Example
           - The following examples assume that you're making the
             firewall changes as a normal user with ``sudo`` privileges.
@@ -1503,7 +1475,7 @@ elements. The following style differences are highlighted:
             :guilabel:`Next`.
 
    Role names
-     Format using the ``:authrole:`` or ``atlasrole:`` as appropriate
+     Format using the ``:authrole:`` or ``:atlasrole:`` as appropriate
      for the documented product's roles. Otherwise, format as regular
      text.
 
@@ -1551,6 +1523,8 @@ elements. The following style differences are highlighted:
                is ``chown``. The most common syntax used with ``chown``
                is as follows:
 
+               ``chown user:group file1 file2 file3``
+
         * - Rendered Example
           - The main command used to change a file’s owner or group is
             ``chown``. The most common syntax used with ``chown`` is as