Titles and Headings

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.

• 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:

  Type	Grammatical structure	Stand-alone article examples	Product guide examples
  Conceptual	Any grammatical structure that's appropriate, except a verb, gerund, or infinitive	Linux distributions Best practices for backing up your data	Core concepts How monitoring works Limitations of detaching from MongoDB networks
  Step-by-step instructions (a task)	An imperative verb Note For specific guidelines for headings within tasks, see Tasks.	Identify network interfaces on Linux 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
  Reference	A plural noun or a noun phrase	Permissions matrix for Cloud Networks MongoDB Auto Scale glossary	Environment variables for the nova and supernova clients Restore operations 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 Service troubleshooting on Linux	Troubleshooting
  FAQ	A descriptive noun or noun phrase, followed by FAQ	MongoDB Cloud Billing FAQ Scheduled images FAQ	Not applicable

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.

Text Following Titles and Headings

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 a title or heading as an antecedent in the sentence that follows it. That is, be sure to repeat the subject in the first sentence that follows the title or heading, rather than using a pronoun that refers to the title or heading as its antecedent.

Tables of Contents

In addition to using the preceding guidelines when creating titles and headings, use the following guidelines when creating a table of contents (TOC) for a collection of content:

• Entries in the TOC should link only to sections in the content. Don't include a link to an outside resource in the TOC.

• The text of a TOC entry should align with the text of the title or heading to which it links. If the link needs to be shorter, consider shortening the title or heading or providing a more concise title or heading for the TOC. An alternate TOC title or heading should convey the same intent of the full title or heading. To learn more, see Table of Contents Labels.

  Example

  1
  .. toctree::
  2
     :titlesonly:
  3
  4
     Install the Operator </installation>
  5
     Deploy Ops Manager Resources </om-resources>
  6
     Deploy MongoDB Database Resources </mdb-resources>
  7
     /tutorial/modify-resource-image
  8
     /reference
  9
     Release Notes </release-notes>
  10
     MongoDB Community Kubernetes Operator <https://github.com/mongodb/mongodb-kubernetes-operator>

• Don't manually format the TOC. TOC formatting must be consistent and controlled by the code.