From 019fd204b5ed656d404cbef5e4ef6a6d586b8149 Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Thu, 8 May 2025 16:04:52 -0700 Subject: [PATCH 1/8] DOCSP-49580 Update Titles Guidance --- .../style-guide/style/titles-and-headings.txt | 71 +++++++++++++++++-- 1 file changed, 67 insertions(+), 4 deletions(-) diff --git a/source/style-guide/style/titles-and-headings.txt b/source/style-guide/style/titles-and-headings.txt index e734216..428ce5b 100644 --- a/source/style-guide/style/titles-and-headings.txt +++ b/source/style-guide/style/titles-and-headings.txt @@ -7,15 +7,78 @@ 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 Titles Matter? +--------------------- + +A page title is weighted as most relevant to a user's search engine query. Title +pages appropriately to ensure users can find the relevant content +in the MongoDB documentation when using a search engine. + +4 SEO Principles +---------------- + +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 come up with a longer page +title for pages with too short titles. A too short tile does not convey enough information +to the search engine, so a page with too short of a title might be recommended less by search +engines. + +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 Top 250 Search keywords in page titles where applicable. [link to list] +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 (Datatbase Command)". + Capitalization -------------- From 9e9eec6134d87bd15f027c73196fc47626975b04 Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Thu, 8 May 2025 16:48:29 -0700 Subject: [PATCH 2/8] redo section hierarchy --- .../style-guide/style/titles-and-headings.txt | 44 +++++++++---------- 1 file changed, 21 insertions(+), 23 deletions(-) diff --git a/source/style-guide/style/titles-and-headings.txt b/source/style-guide/style/titles-and-headings.txt index 428ce5b..ad91f6d 100644 --- a/source/style-guide/style/titles-and-headings.txt +++ b/source/style-guide/style/titles-and-headings.txt @@ -16,15 +16,15 @@ Titles and Headings This topic provides guidelines for creating titles and headings in documentation. -Why Do Titles Matter? ---------------------- +Why Do Page Titles Matter? +-------------------------- A page title is weighted as most relevant to a user's search engine query. Title pages appropriately to ensure users can find the relevant content in the MongoDB documentation when using a search engine. -4 SEO Principles ----------------- +4 SEO Principles for Page Titles +-------------------------------- Consider the following four SEO principles when naming a page: @@ -56,7 +56,7 @@ 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**. +term is used to refer to read operations, based on what term is most findable. Findability ~~~~~~~~~~~ @@ -129,13 +129,18 @@ words: To learn more about the principles of headline-style capitalization, read `section 8.159 `__ of the *Chicago Manual of Style*. +Guidelines for Titles and Headings +---------------------------------- + +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 follow after the general Style and Structure +subsection. + 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. +The following guidelines apply to all titles and headings; - Create succinct, meaningful, descriptive titles and headings, and place the most important words first. @@ -177,7 +182,7 @@ guides, and tables, figures, and examples follow this list. 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 +- 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. @@ -206,7 +211,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:: @@ -219,13 +224,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 @@ -260,7 +258,7 @@ 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 @@ -294,7 +292,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 @@ -310,9 +308,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 @@ -337,7 +335,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 From c82289fe209eae4bb77b3601681e2dba9b2285e7 Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Thu, 8 May 2025 16:55:07 -0700 Subject: [PATCH 3/8] move table --- .../style-guide/style/titles-and-headings.txt | 113 +++++++++--------- 1 file changed, 59 insertions(+), 54 deletions(-) diff --git a/source/style-guide/style/titles-and-headings.txt b/source/style-guide/style/titles-and-headings.txt index ad91f6d..be4c5e3 100644 --- a/source/style-guide/style/titles-and-headings.txt +++ b/source/style-guide/style/titles-and-headings.txt @@ -92,7 +92,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. @@ -137,60 +137,10 @@ titles and headings. Special considerations for stand-alone articles, product guides, and tables, figures, and examples follow after the general Style and Structure subsection. -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. +Grammatical Structure for Different Page Types +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- 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. - -- 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 @@ -251,6 +201,61 @@ The following guidelines apply to all titles and headings; Scheduled images FAQ - Not applicable +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. + +- Use a consistent grammatical structure for the titles and headings of + specific types of content: + + + Standalone Articles ~~~~~~~~~~~~~~~~~~~ From bf32dbdd64d05b92613387180261303326834d27 Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Thu, 8 May 2025 17:18:35 -0700 Subject: [PATCH 4/8] edits --- .../style-guide/style/titles-and-headings.txt | 39 +++++++++---------- 1 file changed, 18 insertions(+), 21 deletions(-) diff --git a/source/style-guide/style/titles-and-headings.txt b/source/style-guide/style/titles-and-headings.txt index be4c5e3..4b9e952 100644 --- a/source/style-guide/style/titles-and-headings.txt +++ b/source/style-guide/style/titles-and-headings.txt @@ -19,9 +19,9 @@ documentation. Why Do Page Titles Matter? -------------------------- -A page title is weighted as most relevant to a user's search engine query. Title -pages appropriately to ensure users can find the relevant content -in the MongoDB documentation when using a search engine. +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. 4 SEO Principles for Page Titles -------------------------------- @@ -42,9 +42,9 @@ 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 come up with a longer page -title for pages with too short titles. A too short tile does not convey enough information -to the search engine, so a page with too short of a title might be recommended less by search +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. Standardization @@ -56,14 +56,13 @@ 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. +term is used to refer to Read operations, based on what term is most findable. Findability ~~~~~~~~~~~ -Use the Top 250 Search keywords in page titles where applicable. [link to list] -Pay attention to word order in a page title. Include the most relevant words -at the beginning of the title. +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. @@ -75,9 +74,9 @@ Differentiate page titles for pages covering commands with same name but differe 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 +operator, and ``mongosh`` method. For Server Manual pages, you can differentiate between these pages by including the command category in the title, like -"count (Datatbase Command)". +"count (Database Command)". Capitalization -------------- @@ -134,12 +133,15 @@ Guidelines for Titles and Headings 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 follow after the general Style and Structure -subsection. +guides, and tables, figures, and examples can be found in the Product Guides and +Tables, Figures, and Headings subsections. Grammatical Structure for Different Page Types ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Use a consistent grammatical structure for the titles and headings of +specific types of content: + .. list-table:: :widths: 15 25 30 30 :header-rows: 1 @@ -201,8 +203,8 @@ Grammatical Structure for Different Page Types Scheduled images FAQ - Not applicable -Style and Structure -~~~~~~~~~~~~~~~~~~~ +General Style and Structure +~~~~~~~~~~~~~~~~~~~~~~~~~~~ The following guidelines apply to all titles and headings; @@ -251,11 +253,6 @@ The following guidelines apply to all titles and headings; intervene between them. Ensure that such text is meaningful. If it is just filler text, consider whether you can restructure the content. -- Use a consistent grammatical structure for the titles and headings of - specific types of content: - - - Standalone Articles ~~~~~~~~~~~~~~~~~~~ From 83724e4741ac3ab7fa6ca9cdbc5c5d03613d19f4 Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Thu, 8 May 2025 17:31:59 -0700 Subject: [PATCH 5/8] page title structure --- source/style-guide/style/titles-and-headings.txt | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/source/style-guide/style/titles-and-headings.txt b/source/style-guide/style/titles-and-headings.txt index 4b9e952..f0275a7 100644 --- a/source/style-guide/style/titles-and-headings.txt +++ b/source/style-guide/style/titles-and-headings.txt @@ -23,6 +23,15 @@ 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 and version number 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" in search engine results. + 4 SEO Principles for Page Titles -------------------------------- @@ -47,6 +56,10 @@ title for pages with too short titles. A too short title does not convey enough 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 ~~~~~~~~~~~~~~~ From f634c96a59f3d911de00faa63de6b6627486082c Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Thu, 8 May 2025 17:39:45 -0700 Subject: [PATCH 6/8] edit --- source/style-guide/style/titles-and-headings.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/style-guide/style/titles-and-headings.txt b/source/style-guide/style/titles-and-headings.txt index f0275a7..281742e 100644 --- a/source/style-guide/style/titles-and-headings.txt +++ b/source/style-guide/style/titles-and-headings.txt @@ -21,7 +21,7 @@ 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. +Documentation when using a search engine. Page Title Structure ~~~~~~~~~~~~~~~~~~~~ From ccd5dfb7f953dff486a247bade91f2716d42e34a Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Mon, 12 May 2025 13:16:27 -0700 Subject: [PATCH 7/8] mongodb docs appended --- source/style-guide/style/titles-and-headings.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/source/style-guide/style/titles-and-headings.txt b/source/style-guide/style/titles-and-headings.txt index 281742e..5c682e2 100644 --- a/source/style-guide/style/titles-and-headings.txt +++ b/source/style-guide/style/titles-and-headings.txt @@ -26,11 +26,11 @@ Documentation when using a search engine. Page Title Structure ~~~~~~~~~~~~~~~~~~~~ -The product name and version number are automatically appended to Documentation -page titles when they are passed to search engines. +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" in search engine results. +"Install MongoDB - Database Manual v8.0 - MongoDB Docs" in search engine results. 4 SEO Principles for Page Titles -------------------------------- From a69934f419f0f9344e5862a2b9e3287c00a9fec3 Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Tue, 13 May 2025 14:02:08 -0700 Subject: [PATCH 8/8] LT review --- source/style-guide/style/titles-and-headings.txt | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/source/style-guide/style/titles-and-headings.txt b/source/style-guide/style/titles-and-headings.txt index 5c682e2..e719640 100644 --- a/source/style-guide/style/titles-and-headings.txt +++ b/source/style-guide/style/titles-and-headings.txt @@ -51,10 +51,9 @@ 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 +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. +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 and version number count towards title length. This can add around 6-20 characters to the title, depending