Merge pull request #170 from JuliaMongo/DOCSP-33533-followup

(DOCSP-33533) Follow-up small edits

Author: JuliaMongo

source/practices.txt

@@ -2,6 +2,12 @@
 Practices and Processes
 =======================
 
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
 This document provides an overview of the practices and processes.
 
 Commits

source/reference.txt

@@ -18,5 +18,6 @@ Reference
    /reference/lightbox
    /reference/options
    /reference/source-constants
+   /style-guide/markup/format/substitutions
    /reference/suppressing-prevnext-links
    /reference/xmlrole

source/style-guide/error-message-guidelines.txt

@@ -6,6 +6,12 @@ Error Message Guidelines
 
 .. default-domain:: mongodb
 
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
 Developers often ask a technical writer to edit error messages
 that they have written.
 
@@ -65,16 +71,16 @@ control panel.
 
        Include articles (a, an, the) to
        make the sentence complete. If possible, use active voice.
-     - The authentication token isn’t valid.
+     - The authentication token isn't valid.
      - Invalid authentication token.
    * - Use more than one sentence if required for clarity.
 
        Write brief and simple sentences that clearly state the problem.
        Separate the sentences with a period (or question mark, if
        applicable), but not with a semicolon.
-     - Provide a name for each domain. *null* isn’t a valid domain
+     - Provide a name for each domain. *null* isn't a valid domain
        name.
-     - You must provide a name for each domain and *null* isn’t a valid
+     - You must provide a name for each domain and *null* isn't a valid
        name.
    * - Use proper punctuation. For guidelines, see :ref:`punctuation`.
      - ``FED2-013: Token expiration cannot exceed seconds.``
@@ -83,7 +89,7 @@ control panel.
 
        Lines with excessive capitalization are hard to read. Use all
        uppercase letters only for words that require it, such as a
-       keyword, a data type, or a specific table name that’s displayed
+       keyword, a data type, or a specific table name that's displayed
        in all uppercase letters to a database user. For more
        information, see :ref:`capitalization`.
      - The requested image ``$UUID`` has automatic disk resizing
@@ -97,11 +103,11 @@ control panel.
      - The system is out of virtual IP addresses. Contact Support so
        they can allocate more virtual IP addresses.
 
-       The value -1.0 can’t be accepted. Specify a positive integer
+       The value -1.0 can't be accepted. Specify a positive integer
        value for the volume size.
      - The system is out of virtual IP addresses.
 
-       The value -1.0 can’t be accepted.
+       The value -1.0 can't be accepted.
    * - Be specific and provide as much detailed information as
        possible.
      - The live migration of instance
@@ -122,15 +128,15 @@ control panel.
 
        Rewrite messages that imply fault on the part of the user. Use
        passive voice when necessary.
-     - The request couldn’t be understood by the server because of
+     - The request couldn't be understood by the server because of
        malformed syntax.
      - You entered bad request syntax.
    * - Use positive statements.
 
        Positive statements are easier to understand than negative
        statements.
      - The given limit must be less than 50.
-     - The given limit can’t be greater than 50.
+     - The given limit can't be greater than 50.
 
 Message Types
 -------------

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

@@ -4,11 +4,19 @@
 Page Metadata Directives
 ========================
 
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+.. default-domain:: mongodb
+
 meta
 ----
 
-Use ``.. meta::`` to add |html| ``<meta>`` tags to a page. These tags are not
-provide other systems such as web browsers, search engines, and other web 
+Use ``.. meta::`` to add |html| ``<meta>`` tags to a page. These tags
+provide other systems, such as web browsers, search engines, and other web 
 services, with information about the page.
 
 You can specify the ``keywords`` and ``description`` name attributes, which

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

@@ -4,6 +4,12 @@
 Shared Include
 ==============
 
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
 The ``sharedinclude`` directive lets you source content from a file located in
 the MongoDB internal `docs-shared <https://github.com/10gen/docs-shared>`__
 repository. Use this directive when you need to keep the same content in sync

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

@@ -2,6 +2,12 @@
 Lists
 =====
 
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
 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.
 

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

@@ -2,6 +2,12 @@
 Substitutions
 =============
 
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
 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

source/style-guide/seo-guidelines.txt

@@ -4,6 +4,14 @@
 Search Engine Optimization Guidelines
 =====================================
 
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+.. default-domain:: mongodb
+
 Search Engine Optimization (SEO) considers the actual terms that users 
 enter into search engines (keywords) and employs best practices to 
 improve traffic to web pages from search engines.  Close attention to page metadata and keywords in the page content can improve page placement in search results.  The following 
@@ -97,7 +105,7 @@ the following best practices:
 - Use a concise description of the page content that is enticing, if 
   possible.
 
-- Emphasize the “why” for using the page.
+- Emphasize the "why" for using the page.
 
 - Use a maximum of 155 characters.
 

source/style-guide/style/abbreviations.txt

@@ -6,6 +6,12 @@ Abbreviations
 
 .. default-domain:: mongodb
 
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
 - Unless an abbreviation is common, spell out the words of the
   abbreviation on the first use in an article or topic.
 

source/style-guide/style/callouts.txt

@@ -6,9 +6,9 @@ Callouts and Admonitions
 
 .. default-domain:: mongodb
 
-Callouts or admonitions emphasize important or
-helpful information. Use callouts sparingly to avoid clutter on
-the page and to preserve visual impact. 
+Callouts or admonitions emphasize important or helpful information.
+To avoid clutter on the page and to preserve visual impact, use callouts
+sparingly.
 
 Callout Types
 -------------
@@ -69,6 +69,7 @@ You can use the following callouts:
 
 Callout Guidelines
 ------------------
+
 When creating callouts, use the following guidelines:
 
 -  Use the callout type to convey the kind of information you want 
@@ -78,18 +79,23 @@ When creating callouts, use the following guidelines:
    attempt to create callouts using boldface, headings, or custom
    :abbr:`CSS (Cascading Style Sheets)`.
 
+- Don't stack multiple callouts directly after one another, as these can
+  distract users. To avoid stacking callouts, group supplemental information
+  from callouts into a dedicated section.
+
+- If possible, don't use callouts in tables and option lists
+  Callouts reduce the scannability of tables and options lists.
+
 -  Avoid nesting callouts inside tables and other elements.
 
 -  Avoid nesting code blocks inside callouts.
 
 -  Place a callout as close as possible to the information that it
    emphasizes or clarifies.
 
--  Don't "stack" callouts of the same type (for example, by following
-   one labeled note directly with another labeled note). Instead, use
-   separate paragraphs or an unordered list within a single callout.
-   You can have callouts of different types follow one
-   another.
+-  Avoid stacking callouts of the same type. For example, avoid adding
+   one labeled note directly after another labeled note. Instead, use
+   a single callout that contains separate paragraphs or an unordered list.
 
 The following callouts might appear in existing documentation but are
 deprecated. Don't use these callouts in new content:

source/style-guide/style/cloud-account-info.txt

@@ -6,6 +6,12 @@ API Placeholders
 
 .. default-domain:: mongodb
 
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
 When users learn how to use our API, they might copy the code and try
 to use it as given. 
 

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

@@ -4,6 +4,12 @@
 Code Examples
 =============
 
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
 Use the following guidelines when creating blocks of code as input
 or output examples:
 

source/style-guide/style/glossaries.txt

@@ -6,6 +6,12 @@ Glossaries
 
 .. default-domain:: mongodb
 
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
 Create a glossary to document the following items:
 
 -  New, unfamiliar, or unique terms
@@ -14,15 +20,16 @@ Create a glossary to document the following items:
 
 This section provides guidelines for the following items:
 
-.. contents:: On this page
-   :local:
-   :backlinks: none
-   :depth: 1
-   :class: singlecol
+- :ref:`glossary-terms`
+- :ref:`glossary-definitions`
+- :ref:`glossary-xrefs`
+- :ref:`glossary-guidelines`
 
 For guidelines about formatting glossary terms that are used in regular
 text, see :ref:`text-formatting`.
 
+.. _glossary-terms:
+
 Glossary Terms
 --------------
 
@@ -58,6 +65,8 @@ slashes, and apostrophes continue a single word.
 
        newspaper
 
+.. _glossary-definitions:
+
 Glossary Definitions
 --------------------
 
@@ -119,6 +128,8 @@ The following table shows examples.
        and protocols that programmers can use to create application
        services by using an open application.
 
+.. _glossary-xrefs:
+
 Cross-References to Glossary Terms
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -168,6 +179,8 @@ glossary:
        To recover by dropping the selected database and re-creating it.
        *Contrast with* copy over.
 
+.. _glossary-guidelines:
+
 Guidelines for a Comprehensive Glossary
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -196,7 +209,7 @@ comprehensive glossary:
    information about third-party terms. A MongoDB glossary should
    contain mainly MongoDB terms. If the user could find the meaning
    outside of a MongoDB document by using a browser search, then we
-   probably don’t need to include it in the glossary. For example,
+   probably don't need to include it in the glossary. For example,
    *Apache*.
 
 -  If a term is specific to one MongoDB service, start the definition

source/style-guide/style/ip-addresses.txt

@@ -6,6 +6,12 @@ IP Addresses
 
 .. default-domain:: mongodb
 
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
 An *IP address* uses a sequence of numbers to uniquely identify a
 particular computer on the Internet.