Edits

Author: JuliaMongo

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/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

@@ -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,25 @@ 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 admonitions directly after one another, as these
+  can be distracting for users. To avoid stacking admonitions, group
+  supplemental information from admonitions into a dedicated section.
+
+- Don't use admonitions in tables and option lists, if possible, because
+  admonitions reduce 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
+-  Avoid "stack" callouts of the same type. For example, avoid adding
+   one labeled note directly after 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.
+   another, if necessary, but if possible, avoid such situations also.
 
 The following callouts might appear in existing documentation but are
 deprecated. Don't use these callouts in new content:

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

source/style-guide/style/links-and-cross-references.txt

@@ -75,35 +75,30 @@ about MongoDB concepts can click through and explore the linked content.
 Avoid Inline References in Tutorials
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-- Don't add inline textual references in tutorials or stepped procedures. 
+- Avoid adding inline textual references in tutorials or stepped procedures. 
 
-  If users follow inline references while in the middle of a procedure, this complicates navigating back and reorienting themselves with
-  their current step.
+  If users follow inline references while in the middle of a procedure,
+  they might have difficulty navigating back and reorienting themselves
+  with their current step.
 
-  Inline textual references may be appropriate for more reference-heavy pages,
-  or tasks that aren't part of a streamlined tutorial for a particular action.
-
-- Don't stack multiple admonitions directly after one another, as these
-  can be distracting for users. To avoid stacking admonitions, group
-  supplemental information from admonitions into a dedicated section.
-
-- Don't use admonitions in tables and option lists, if possible, because
-  admonitions reduce scannability of tables and options lists.
+  Inline textual references may be appropriate for more reference-heavy pages.
 
 Minimize Repeated Links
 ~~~~~~~~~~~~~~~~~~~~~~~
 
 - Don't link to the same target multiple times in the same section.
 
-  If a page is long and contains many sections, you may link to a target
-  once or twice from this page. This helps users who navigate to a section
-  far down on a page and may miss the initial reference at the top of the
-  page. However, don't link to a target more than twice on the same page.
+  You may link to the same target more than once on the same page, but
+  think carefully about whether it's absolutely necessary. For example,
+  if a page is long and contains many sections, then it might be helpful
+  to link to a target once or twice from this page to help users who
+  navigate to a section far down on a page and may miss the initial
+  reference at the top of the page.
 
-- When adding repeated links, use the same style for each link.
+- If you add repeated links, use the same style for each link.
   Consider whether a plaintext link or a monospace link is appropriate.
-  Plaintext links may be less visually distracting than monospace links,
-  which have the surrounding block.
+  Plaintext links might be less visually distracting than monospace links,
+  which have a surrounding block.
 
 Make Link Text Clear
 ~~~~~~~~~~~~~~~~~~~~