DOCSP-49580 Update Titles Guidance

source/style-guide/seo-guidelines.txt

@@ -65,9 +65,73 @@ practices:
    example, use "This MongoDB Atlas course..." instead of "This Getting 
    Started with Atlas course...".
 
+.. _seo-guidelines-titles:
+
 Titles
 ------
 
+Consider the following four SEO principles when naming a page:
+
+- Title Length
+
+- Standardization
+
+- Findability
+
+- Disambiguation
+
+Each of the following four subsections describe one of the above principles. 
+
+Title Length
+~~~~~~~~~~~~
+
+Titles should be between 30-60 characters long. Pages with titles longer than 60 characters
+are typically truncated by search engines. A too short title does not convey enough information
+to the search engine, so a page with a too short title might be recommended less by search
+engines. Search engines might also create a longer page title for pages with too short titles.
+
+When considering title length, keep in mind that the product name, version 
+number, and "MongoDB Docs" are automatically appended when the title is passed 
+to a search engine. For example, for a v8.0 Server Manual page titled 
+"Install MongoDB", the title is 15 characters long. The full title passed to search
+engines ("Install MongoDB - Database Manual v8.0 - MongoDB Docs") is 53 characters long.
+The appended additions to the title can add around 18-35 
+characters to the title, depending on the length of the product name. 
+
+Standardization
+~~~~~~~~~~~~~~~
+
+For pages across MongoDB documentation covering similar concepts, use consistent 
+wording in the page titles to ensure a consistent user experience.
+
+For example, multiple pages in the documentation cover the Read CRUD operation. 
+The Read CRUD operation can be referred to as a read, find, or query operation.
+Page titles for pages documenting the Read operation should be consistent in what
+term is used to refer to Read operations, based on what term is most findable. 
+
+Findability
+~~~~~~~~~~~
+
+Use the most relevant keywords in a page title. Pay attention to word order in a 
+page title. Include the most relevant words at the beginning of the title.
+
+When in doubt, search your potential page title in a search engine. The top five search 
+results should be similar content to the page you are titling. 
+
+Disambiguation
+~~~~~~~~~~~~~~
+
+Differentiate page titles for pages covering commands with same name but different
+functions by adding the command category in the title.
+
+For example, ``count`` is a database command, aggregation stage, aggregation 
+operator, and  ``mongosh`` method. For Server Manual pages, you can differentiate
+between these pages by including the command category in the title, like
+"count (Database Command)".
+
+General Guidelines
+~~~~~~~~~~~~~~~~~~
+
 Use the following SEO best practices for page and subsection titles:
 
 - Use a maximum of 70 characters.

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

@@ -7,15 +7,31 @@
 Titles and Headings
 ===================
 
-This topic provides guidelines for creating titles and headings in
-documentation.
-
 .. contents:: On this page
    :local:
    :backlinks: none
-   :depth: 1
+   :depth: 2
    :class: singlecol
 
+This topic provides guidelines for creating titles and headings in
+documentation.
+
+Why Do Page Titles Matter?
+--------------------------
+
+A page title is weighted as most relevant to a user's search engine query. Name
+pages appropriately to ensure users can find relevant content in the MongoDB 
+Documentation when using a search engine. 
+
+Page Title Structure
+~~~~~~~~~~~~~~~~~~~~
+
+The product name, version number, and "MongoDB Docs" are automatically appended to 
+Documentation page titles when they are passed to search engines.
+
+For example, a v8.0 Server Manual page titled "Install MongoDB" will appear as
+"Install MongoDB - Database Manual v8.0 - MongoDB Docs" in search engine results. 
+
 Capitalization
 --------------
 
@@ -29,7 +45,7 @@ Capitalization
 .. _headline-style-capitalization:
 
 Guidelines for Headline-Style Capitalization
---------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 AP headline-style capitalization uses initial uppercase letters for the
 first, last, and all the significant words in the title.
@@ -66,63 +82,25 @@ words:
    To learn more about the principles of headline-style capitalization,
    read `section 8.159 <https://www.chicagomanualofstyle.org/book/ed17/part2/ch08/psec159.html>`__ of the *Chicago Manual of Style*.
 
-Style and Structure
-~~~~~~~~~~~~~~~~~~~
-
-Use the guidelines in this section to create effective and consistent
-titles and headings. The following guidelines apply to all titles and
-headings; special considerations for stand-alone articles, product
-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. 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
-  first word.
-
-- Avoid showing both an abbreviation and its spelled-out term in a
-  title or heading. To help control the length of titles and headings,
-  show the abbreviation in the title or heading and then define it in
-  the first paragraph of the text.
+.. _general-title-guidance:
 
-- If you show a literal term (such as a command or option name) in a
-  title or heading, follow it with an appropriate noun.
+Guidelines for Titles and Headings
+----------------------------------
 
-- Don't end a title or heading with a colon or period. If the title or
-  heading is in the form of a question, end it with a question mark.
+Use the guidelines in the following subsections to create effective and consistent
+titles and headings. Special considerations for stand-alone articles, product
+guides, and tables, figures, and examples can be found in the Product Guides and
+Tables, Figures, and Headings subsections. 
 
-- Don't apply font treatments (bold, italics, or monospace) to text in
-  a title or heading.
+.. _title-grammar:
 
-- Don't include trademark symbols in titles or headings. Show the
-  symbol on the first use of the trademark in text.
-
-- Avoid having only a single heading at any level (for example, a
-  single subsection in an article or section). If you find that you
-  have a single heading at any one level, consider whether you can
-  reorganize the information to either eliminate the heading or add a
-  second one at that level.
-
-- Avoid having more than two levels of sections within an article or
-  topic. If you use more than two levels of sections, consider whether
-  you can reorganize to make the structure flatter.
-
-- Don’t "stack" titles or headings. That is, don’t immediately follow a
-  title or heading with another title or heading. Text should always
-  intervene between them. Ensure that such text is meaningful. If it is
-  just filler text, consider whether you can restructure the content.
+Grammatical Structure for Different Page Types
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-- Use a consistent grammatical structure for the titles and headings of
-  specific types of content:
+Use a consistent grammatical structure for the titles and headings of
+specific types of content:
 
-  .. list-table::
+.. list-table::
      :widths: 15 25 30 30
      :header-rows: 1
 
@@ -134,70 +112,119 @@ guides, and tables, figures, and examples follow this list.
      * - Conceptual
        - Any grammatical structure that's appropriate, except a verb,
          gerund, or infinitive
-       - Linux distributions
+       - Linux Distributions
 
-         Best practices for backing up your data
+         Best Practices for Backing Up Your Data
        - Core concepts
 
-         How monitoring works
+         How Monitoring Works
 
-         Limitations of detaching from MongoDB networks
+         Limitations of Detaching from MongoDB Networks
 
-     * - Step-by-step instructions (a task)
+     * - Tutorial or high-level process
        - An imperative verb
 
          .. note::
             For specific guidelines for headings within tasks, see
             :ref:`tasks`.
-       - Identify network interfaces on Linux
+       - Identify Network Interfaces on Linux
 
-         Prepare data disks on servers running Windows
+         Prepare Data Disks on Servers Running Windows
 
-         Set up Mobile Sync for Webmail
-       - Sign up for a MongoDB Atlas account
-
-     * - Tutorial or high-level process
-       - A gerund
-       - Understanding logrotate
-
-         Customizing Apache web logs
-       - Working with your first message queue
+         Set Up Mobile Sync for Webmail
+       - Sign Up for a MongoDB Atlas Account
 
      * - Reference
        - A plural noun or a noun phrase
-       - Permissions matrix for Cloud Networks
+       - Permissions Matrix for Cloud Networks
 
-         MongoDB Auto Scale glossary
-       - Environment variables for the nova and supernova clients
+         MongoDB Auto Scale Glossary
+       - Environment Variables for the Nova and Supernova Clients
 
-         Restore operations
+         Operators and Collectors
 
-         cURL command summary
+         cURL Command Summary
 
      * - Troubleshooting
        - A grammatical structure that's appropriate for the type of
          content (a troubleshooting topic can contain task, tutorial,
          concept, or reference information)
-       - Troubleshoot alarms
+       - Troubleshoot Alarms
 
-         Service troubleshooting on Linux
+         Service Troubleshooting on Linux
        - Troubleshooting
 
      * - FAQ
        - A descriptive noun or noun phrase, followed by *FAQ*
        - MongoDB Cloud Billing FAQ
 
-         Scheduled images FAQ
+         Scheduled Images FAQ
        - Not applicable
 
+SEO Guidelines for Titles
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To learn more about SEO guidelines for titles, see the 
+:ref:`Titles <seo-guidelines-titles>` section of Search Engine Optimization Guidelines.
+
+General Style and Structure
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following guidelines apply to all titles and headings:
+
+- Create succinct, meaningful, descriptive titles and headings, and
+  place the most important words first.
+
+- 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
+  first word.
+
+- Avoid showing both an abbreviation and its spelled-out term in a
+  title or heading. To help control the length of titles and headings,
+  show the abbreviation in the title or heading and then define it in
+  the first paragraph of the text.
+
+- If you show a literal term (such as a command or option name) in a
+  title or heading, follow it with an appropriate noun.
+
+- Don't end a title or heading with a colon or period. If the title or
+  heading is in the form of a question, end it with a question mark.
+
+- Don't apply font formatting (bold, italics, or monospace) to text in
+  a title or heading.
+
+- Don't include trademark symbols in titles or headings. Show the
+  symbol on the first use of the trademark in text.
+
+- Avoid having only a single heading at any level (for example, a
+  single subsection in an article or section). If you find that you
+  have a single heading at any one level, consider whether you can
+  reorganize the information to either eliminate the heading or add a
+  second one at that level.
+
+- Avoid having more than two levels of headings within an article or
+  topic. If you use more than two levels of headings, consider whether
+  you can reorganize to make the structure flatter.
+
+- Don't "stack" titles or headings. That is, don't immediately follow a
+  title or heading with another title or heading. Text should always
+  intervene between them. Ensure that such text is meaningful. If it is
+  just filler text, consider whether you can restructure the content.
+
 Standalone Articles
 ~~~~~~~~~~~~~~~~~~~
 
 In addition to the preceding guidelines, use the following guidelines
 when creating titles and headings for stand-alone articles on the
 Support site or in other collections of documentation:
 
-- Create article titles that don’t rely on body text or other titles
+- Create article titles that don't rely on body text or other titles
   for their meaning (that are, in other words, independent of context).
   Users should be able to tell from a title whether the information in
   the article is relevant to their needs. Avoid ambiguous one-word
@@ -231,7 +258,7 @@ when creating titles and headings for sections in product guides:
 - Define consistent heading levels, and do not skip levels.
 
 Tables, Figures, and Examples
------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 As a general rule, tables, figures, and examples should have titles
 (also called captions). However, tables, figures, and examples in
@@ -247,9 +274,9 @@ when creating titles for tables, figures, and examples:
 -  Avoid using a title that duplicates an article or section title.
 
 Text Following Titles and Headings
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+----------------------------------
 
-Don’t immediately follow a title or heading with another title or
+Don't immediately follow a title or heading with another title or
 heading. Instead, follow a title or heading with body text.
 
 The body text must be independent from the title or heading. Don't use
@@ -274,7 +301,7 @@ to the title or heading as its antecedent.
        This article briefly describes how to do this.
 
 Tables of Contents
-~~~~~~~~~~~~~~~~~~
+------------------
 
 In addition to using the preceding guidelines when creating titles and
 headings, use the following guidelines when creating a table of