Docs Menu
Docs Home
/
MongoDB Meta Documentation
/
MongoDB Documentation Style Guide
/
Style Guidelines

Lists

On this page

The following types of lists are commonly used in documentation:

  • Ordered lists or numbered lists. The list items must be performed or considered in a particular order.

  • Unordered lists or bulleted lists. The order of the list items isn't important.

Introductory Text

Introduce a list with context. In most cases, you use a sentence; you can introduce procedures with a heading. Use the following guidelines when introducing lists.

Guideline
Example

Introduce a list with a sentence, and end the sentence with a colon. If another sentence intervenes between the introductory sentence and the list, end the introductory sentence with a period instead of a colon.

Note

Avoid using a fragment to introduce a list. Users might find a fragment more difficult to understand than a full sentence. If a full sentence makes the introduction awkward or redundant, use a sentence stem to introduce the list and ensure the list items complete the sentence. Consider accessibility and screen readers because introductory text plays a crucial role in providing context and navigation cues for individuals who rely on auditory output. To learn more, see Section508.

You can use this product to perform the following tasks:

You can use this product to perform the following tasks. You must extract objects from the database to complete these tasks.

For a partial list only, use the verb include in the introductory text.

The directory includes the following files:

(Includes is correct only if you're listing some, but not all, files in the directory.)

Don't quantify items in introductory text. Quantifying items could cause an error if the list changes.

Use:

The following methods are available:

Don't use:

The following three methods are available:

Don’t tell users to "do the following." The verb do is weak, using following as a noun in this context is incorrect, and the whole phrase is ambiguous.

Use a stronger and more meaningful verb. Use following only as an adjective, unless you're referring to an entourage, posse, retinue, or group of fans. Ensure that the introduction to a list provides enough context for users to understand what information the list is providing.

Use:

You can use this product to perform the following tasks:

The following methods are available:

Don't use:

You can use this product to do the following:

The following are available:

List Items

Use the following guidelines when writing list items:

  • Capitalize the first letter of each list item unless the first letter must be lowercase.

  • Make all list items parallel. For example, all items start with fragments, or all items use sentences. A list can have a mix of fragments and sentences as long as all of the items start with a fragment.

  • Punctuate list items as follows:

    • In a list of only sentences, including imperative statements, use punctuation at the end of each item.

    • In a list of only fragments, use no punctuation at the end of each item.

    • In a list of fragments, some or all of which are followed by sentences, use punctuation at the end of every fragment and sentence in the list.

  • Don't connect separate list items with commas or conjunctions (and, or).

  • Avoid using articles (a, an, the) to start list items.

  • When a list provides a series of terms or phrases and then more information about them, format the list as follows:

    • Show the term or phrase in bold. Using bold makes the list easier to scan.

    • If you need to separate the initial term or phrase from the information that follows it, use a colon. However, if you don't need a separator, don't use one. (For an example of a list in which separators aren't necessary, see the list at the top of this topic.)

  • Unless another order makes sense or is preferable, alphabetize list items.

List Examples

The following sections show examples of the indicated types of lists.

All List Items Are Sentences

When you create an AWS PrivateLink, the following limitations apply:

  • You can use AWS PrivateLink to connect to Atlas clusters running MongoDB version 3.6 or later.

  • AWS PrivateLink must be active in all regions into which you deploy a multi-region cluster. You receive an error if AWS PrivateLink is active in some, but not all, targeted regions.

  • You can do only one of the following:

    • Create multiple private endpoints in a single region.

    • Create one private endpoint in multiple regions.

    If you create more than one private endpoint in a single region, you can’t create private endpoints in other regions.

All List Items Are Fragments

The example creates a cluster instance called my-atlas-cluster with the following characteristics:

  • M10 tier

  • Volume size of 2 GB

All List Items Are Imperative Statements

You can use Cloud Backup to perform the following actions:

  • Select the databases from your cluster that you want to back up.

  • Run your backups manually or on a schedule.

  • See the activity from all your backups.

  • Use AES-256 encryption with a private encryption key that only you know.

  • Restore individual files and folders from a particular date.

  • Save space with incremental backups that save only the changed portions of files.

  • Create unlimited backups.

List Items Mix Fragments and Sentences

To run the examples in this guide, the following prerequisites are required:

  • MongoDB Atlas account. To sign up for a MongoDB Atlas account, go to the MongoDB Cloud signup page.

  • MongoDB username and password that you specified during registration.

List that Provides Terms and More Information

When creating your Atlas cluster, choose one of the following cloud providers:

  • Amazon Web Services: AWS offers 28 cluster tiers in 18 regions.

  • Microsoft Azure: Azure offers 16 cluster tiers in 33 regions.

  • Google Cloud Platform: GCP offers 19 cluster tiers in 21 regions.

Back

Links and Cross-References

Next

Messages