Titles and Headings

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.

Title Length

Titles should be between 30-60 character 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 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)".

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.

Capitalize all words in the title except for the following types of words:

• Articles (a, an, the) unless the article is the first word in the title or follows a colon

• Coordinating conjunctions (and, but, for, nor, or, yet, so) unless the conjunction is the first word in the title

• Prepositions of any length, unless the preposition is the first or the last word in the title or is part of a verb phrase

• The word to in an infinitive phrase unless to is the first word in the title

• Second elements attached by hyphens to prefixes unless they're proper nouns or proper adjectives

• Words that always begin with a lowercase letter, such as literal command names or certain product or software names

Grammatical Structure for Different Page Types

Use a consistent grammatical structure for the titles and headings of specific types of content:

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 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 titles, such as "Overview."

• Don't number titles to indicate their placement in a series of articles. Indicate the order of articles within the content of the article, referring users to information that they should have read previously before reading the current article. Use links to provide navigation to preceding and following articles in the series.

• Start with the highest level of heading that is approved for headings (for example, h3), and do not skip heading levels.

Product Guides

In addition to the preceding guidelines, use the following guidelines when creating titles and headings for sections in product guides:

• If possible, limit titles and headings to 60 characters for legibility in the TOC pane.

• Consider that titles and headings are written within the context of the content set in which they are presented. Therefore, you can usually omit "context-setting" terms. For example, if the content set is about servers, you can usually omit "for servers" from the title or heading. (For example, "Attach a network to a server" can be shortened to "Attach a network" with no loss of clarity.)

• 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 procedures and tutorials don't normally require titles.

In addition to the preceding guidelines, use the following guidelines when creating titles for tables, figures, and examples:

• Place the title above the table, figure, or example, not below it.

• Tag the title as bold.

• Avoid using a title that duplicates an article or section title.