diff --git a/source/style-guide/seo-guidelines.txt b/source/style-guide/seo-guidelines.txt index 40062f3e..bcfc78ae 100644 --- a/source/style-guide/seo-guidelines.txt +++ b/source/style-guide/seo-guidelines.txt @@ -65,9 +65,88 @@ practices: example, use "This MongoDB Atlas course..." instead of "This Getting Started with Atlas course...". +.. _seo-guidelines-titles: + Titles ------ +Search engines weight page titles heavily. Name pages appropriately to ensure users can find +relevant content in the MongoDB Documentation when they use a search engine. + +Consider the following SEO principles when you name a page: + +- Title Length + +- Standardization + +- Findability + +- Disambiguation + +The following subsections describe these principles. + +Title Length +~~~~~~~~~~~~ + +Titles should include 30-60 characters. Search engines often truncate pages +with titles longer than 60 characters. Titles with fewer than 30 characters +convey limited information to search engines, so search engines recommend these +pages less often. Search engines might also create a longer page title for pages with +titles under 30 characters. + +As described in the :ref:`Page Title Structure ` subsection, +the product name, version number, and "MongoDB Docs" are automatically appended to a title +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 when passed to a search engine ("Install MongoDB - Database Manual v8.0 - MongoDB Docs") +is 53 characters long. The appended additions to the title can add about 18-35 +characters to the title, depending on the length of the product name. + +Standardization +~~~~~~~~~~~~~~~ + +For pages across MongoDB documentation that cover 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. +You can refer to the Read CRUD operation as a read, find, or query operation. +Titles for pages that document the Read operation should use consistent terminology +to refer to Read operations, based on the most findable term. + +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 resemble the content on your page. + +Disambiguation +~~~~~~~~~~~~~~ + +For pages that cover commands with the same name but different +functions, add the command categories to the page titles to differentiate the pages. + +For example, ``count`` is a database command, aggregation stage, aggregation +operator, and ``mongosh`` method. For Server Manual pages, you +can include the command category in the title, like +"count (Database Command)," to differentiate between these pages. + +.. _titles-page-title-structure: + +Page Title Structure +~~~~~~~~~~~~~~~~~~~~ + +The product name, version number, and "MongoDB Docs" are automatically appended to +Documentation page titles when the title is passed to a search engine. + +For example, a v8.0 Server Manual page titled "Install MongoDB" appears as +"Install MongoDB - Database Manual v8.0 - MongoDB Docs" in search engine results. + +General Guidelines +~~~~~~~~~~~~~~~~~~ + Use the following SEO best practices for page and subsection titles: - Use a maximum of 70 characters. diff --git a/source/style-guide/style/titles-and-headings.txt b/source/style-guide/style/titles-and-headings.txt index e7342163..854f79c4 100644 --- a/source/style-guide/style/titles-and-headings.txt +++ b/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 for SEO? +---------------------------------- + +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 a title is passed to a search engine. + +For example, a v8.0 Server Manual page titled "Install MongoDB" appears 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 `__ 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. +.. _general-title-guidance: -- Create succinct, meaningful, descriptive titles and headings, and - place the most important words first. +Guidelines for Titles and Headings +---------------------------------- -- Ensure that each title and heading is unique. Identical titles, even - between documentation sets, might compete in search results. +Use the guidelines in the following subsections to create effective and consistent +titles and headings. You can find special considerations for stand-alone articles, product +guides, tables, figures, and examples in the :ref:`Product Guides ` and +:ref:`Tables, Figures, and Headings ` subsections. -- Don't include "MongoDB" in a title unless the page is a product - landing page. +.. _title-grammar: -- Include articles, prepositions, and punctuation as needed for - clarity. However, avoid using an article (*a*, *an*, or *the*) as the - first word. +Grammatical Structure for Different Page Types +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- 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. +Use a consistent grammatical structure for the titles and headings of +specific types of content: -- 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: - - .. list-table:: +.. list-table:: :widths: 15 25 30 30 :header-rows: 1 @@ -134,62 +112,111 @@ 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 - - Prepare data disks on servers running Windows + - Identify Network Interfaces on Linux - Set up Mobile Sync for Webmail - - Sign up for a MongoDB Atlas account - - * - Tutorial or high-level process - - A gerund - - Understanding logrotate + Prepare Data Disks on Servers Running Windows - 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 ` 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 ~~~~~~~~~~~~~~~~~~~ @@ -197,7 +224,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 @@ -212,6 +239,8 @@ Support site or in other collections of documentation: - Start with the highest level of heading that is approved for headings (for example, h3), and do not skip heading levels. +.. _titles-product-guides: + Product Guides ~~~~~~~~~~~~~~ @@ -230,8 +259,10 @@ when creating titles and headings for sections in product guides: - Define consistent heading levels, and do not skip levels. +.. _titles-table-figures-ex: + 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 +278,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 +305,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