(DOCSP-41504, DOCSP-41866, DOCSP-41583): Adds TOC label guidance, SEO, and spelling updates. (#175)

* (DOCSP-41504): Adds TOC label guidance, SEO, and spelling updates.

* (DOCSP-41504): Incorporated feedback.

* (DOCSP-41504): Incorporated Jeff's feedback.

Author: corryroot

source/style-guide/seo-guidelines.txt

@@ -76,6 +76,9 @@ Use the following SEO best practices for page and subsection titles:
 
 - Use unique page titles. Identical titles, even between 
   documentation sets, compete in search results.
+
+- Don't include "MongoDB" in a title unless the page is a product 
+  landing page.
 
 To learn more, see :ref:`titles-and-headings`.
 

source/style-guide/style/index.txt

@@ -40,6 +40,7 @@ instructions for applying style conventions.
    /style-guide/style/punctuation
    /style-guide/style/symbols
    /style-guide/style/tables
+   /style-guide/style/toc-labels
    /style-guide/style/tasks
    /style-guide/style/telephone-numbers
    /style-guide/style/text-formatting

source/style-guide/style/product-names-version-numbers.txt

@@ -19,18 +19,22 @@ the following guidelines:
    * - Spell out and properly capitalize MongoDB product and service
        names.
      -
-       - MongoDB Atlas
-       - MongoDB Compass
+       - Atlas
+       - Compass
 
-   * - Use the full MongoDB product name on the first mention.
-       Subsequent mentions may use the product name without MongoDB.
+   * - Don't include "MongoDB" in a title unless the page is a product 
+       landing page.
+
+       Use the full MongoDB product name on the first mention in the 
+       body text. Subsequent mentions may use the product name without 
+       MongoDB.
 
      - .. list-table::
           :widths: 50 50
           :header-rows: 1
 
-          * - First mention
-            - Subsequent mentions
+          * - Landing page or first mention
+            - All other mentions
 
           * - MongoDB Atlas
             - Atlas
@@ -85,7 +89,7 @@ the following guidelines:
    * - Use full, three-digit version numbers when referring to a
        specific release or feature. Use the two-digit release series
        when referring to a common feature.
-     - MongoDB Ops Manager 4.2.13 supports queryable restores for
+     - Ops Manager 4.2.13 supports queryable restores for
        MongoDB 4.2 deployments.
 
 Examples
@@ -101,7 +105,7 @@ Examples
    * - Use Atlas to create a cluster.
      - Use Atlas to create a Cluster.
 
-   * - Use MongoDB Ops Manager to create users.
+   * - Use Ops Manager to create users.
      - Use MOM to create Users.
 
    * - You can add collections to a database.

source/style-guide/style/titles-and-headings.txt

@@ -74,8 +74,11 @@ guides, and tables, figures, and examples follow this list.
 - Create succinct, meaningful, descriptive titles and headings, and
   place the most important words first.
 
-- Ensure that each title and heading is unique within a given content
-  set.
+- Ensure that each title and heading is unique. Identical titles, even 
+  between documentation sets, might compete in search results.
+
+- Don't include "MongoDB" in a title unless the page is a product 
+  landing page.
 
 - Include articles, prepositions, and punctuation as needed for
   clarity. However, avoid using an article (*a*, *an*, or *the*) as the
@@ -277,11 +280,12 @@ contents (TOC) for a collection of content:
 -  Entries in the TOC should link only to sections in the content.
    Don't include a link to an outside resource in the TOC.
 
--  The text of a TOC entry should match the text of the title or
+-  The text of a TOC entry should align with the text of the title or
    heading to which it links. If the link needs to be shorter, consider
    shortening the title or heading or providing a more concise title or
    heading for the TOC. An alternate TOC title or heading should convey
-   the same intent of the full title or heading.
+   the same intent of the full title or heading. To learn more, see 
+   :ref:`toc-labels`.
 
    .. example::
 

source/style-guide/style/toc-labels.txt

@@ -0,0 +1,115 @@
+.. _toc-labels:
+
+========================
+Table of Contents Labels
+========================
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+Table of Contents (TOC) labels refer to the headings or titles used to 
+represent the various sections or pages of our documentation in the 
+TOC. The TOC provides an organized list of the documentation's 
+structure and content.
+
+Each entry in the TOC typically includes a label or heading that 
+corresponds to a section or page in the documentation. These labels 
+give users a quick overview of the topics covered and help them 
+navigate to specific parts of the documentation more efficiently.
+
+When you create a TOC, you can generate these labels automatically 
+based on the titles of your pages, or specify labels that differ from 
+the page title.
+
+Page titles and Table of Contents (TOC) labels serve distinct purposes. 
+We should craft them with different considerations.
+
+TOC labels and page titles can match. However, we should define them 
+separately even when they match for added flexibility. This approach 
+ensures that we can easily implement any future changes without 
+affecting the other element. Separate definitions for TOC labels and 
+page titles contribute to organized content management and a seamless 
+user experience.
+
+While both page titles and TOC labels contribute to the overall user 
+experience, page titles focus more on attracting users and SEO, while 
+TOC labels prioritize representing the document's structure and aiding 
+in navigation within the document itself.
+
+Page Titles
+-----------
+
+- Optimize page titles for search engines. They should include relevant 
+  keywords to improve the page's discoverability in search results. To 
+  learn more, see :ref:`seo-guidelines`.
+
+- Create succinct, meaningful, descriptive page titles, and place the 
+  most important words first. Page titles should have a maximum of 70 
+  characters and provide a quick overview of the content. Search 
+  results or browser tabs might truncate extra long titles. Avoid 
+  excessive or irrelevant words (keyword stuffing).
+
+- While we should craft concise titles, include enough information to 
+  confirm to the user that they have landed in the right place. A page 
+  title can provide more detail than a TOC label.
+
+- Ensure that each title and heading is unique. Identical titles, even 
+  between documentation sets, might compete in search results.
+
+- Don't include "MongoDB" in a title unless the page is a product 
+  landing page.
+
+- Aim to attract users and encourage them to click on the link. Include 
+  phrases users might search for, or tasks they might want to 
+  accomplish.
+
+- Create page titles that are readable and effective on various 
+  devices, including mobile. This involves considering character limits 
+  and readability on smaller screens.
+
+- Use a consistent grammatical structure, style, and tone across all 
+  page titles to maintain a unified and professional appearance. For 
+  example, use verbs to indicate procedural content.
+
+
+To learn more, see :ref:`titles-and-headings`.
+
+TOC Labels
+----------
+
+- While the automatic labels make it easier for writers to 
+  update the TOC as the content evolves, long titles interfere with 
+  efficient navigation. We recommend that you specify TOC labels to 
+  enhance the document's accessibility and usability.
+
+- Craft clear and descriptive TOC labels that convey the content of 
+  each section or page accurately. Users should understand the context 
+  from the TOC label and its placement in the overall TOC hierarchy.
+
+- Ensure your TOC label fits on a single line of text. Let the 
+  placement of the TOC label in the overall TOC hierarchy provide 
+  context. Avoid redundancy and repetition. The page title itself can 
+  provide more detail and confirm to the user that they have landed in 
+  the right place. To this end, you can use industry standard 
+  abbreviations and the ampersand when needed.
+
+  .. important::
+
+     In favor of brevity, TOC labels do allow for the the ampersand ( & ) symbol.
+
+- Don't stray so far from the original page title that you disorient 
+  the user.
+
+- TOC labels should follow a logical order that reflects the 
+  documentation's flow. You might include numbering or an order that 
+  makes sense for the documentation's purpose.
+
+- TOC labels primarily aid user navigation. Users should be able to 
+  quickly locate and go to specific sections of interest.
+
+- In technical documentation, TOC labels may use specialized technical 
+  terminology and acronyms to accurately represent the content within 
+  each section or page.

source/style-guide/terminology/general-term-guidelines/use-consistent-terms.txt

@@ -11,6 +11,12 @@ industry dictionary or style guide, or for your particular project.
 Each word or phrase should have only one meaning, and should be used
 consistently throughout the documentation.
 
+- Use American English spelling instead of British English spelling.
+  
+  .. example::
+
+     Use "gray" instead of "grey" and "color" instead of "colour".
+
 - The |mdbsg| uses the *Merriam-Webster’s Collegiate Dictionary*. 11th
   ed. Springfield, MA: Merriam-Webster, 2003. Continually updated at
   https://www.merriam-webster.com/.