DOCSP-49580 Update Titles Guidance

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

@@ -7,15 +7,90 @@
 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. 
+
+4 SEO Principles for Page 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 character long. Pages with titles longer than 60 characters
+are typically truncated by search engines. Search engines might create a longer page 
+title for pages with too short titles. 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.
+
+When considering title length, keep in mind that the product name and version number
+count towards title length. This can add around 6-20 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)".
+
 Capitalization
 --------------
 
@@ -29,7 +104,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 +141,21 @@ 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.
-
-- 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 treatments (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.
+Guidelines for Titles and Headings
+----------------------------------
 
-- 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.
+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 "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
 
@@ -143,7 +176,7 @@ guides, and tables, figures, and examples follow this list.
 
          Limitations of detaching from MongoDB networks
 
-     * - Step-by-step instructions (a task)
+     * - Tutorial or high-level process
        - An imperative verb
 
          .. note::
@@ -156,13 +189,6 @@ guides, and tables, figures, and examples follow this list.
          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
-
      * - Reference
        - A plural noun or a noun phrase
        - Permissions matrix for Cloud Networks
@@ -190,14 +216,64 @@ guides, and tables, figures, and examples follow this list.
          Scheduled images FAQ
        - Not applicable
 
+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 treatments (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 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.
+
 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 +307,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 +323,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 +350,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