Lists#

The following types of lists are commonly used in documentation:

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

  • Unordered lists, which are delineated by bullets (and therefore also referred to as bullet lists). The order of the list items isn’t important.

This topic provides the following guidelines for lists:

Introductory text#

Provide context for a list by introducing it. In most cases, you use a sentence; however, 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 fragments to introduce lists. Fragments can be harder to understand than sentences.

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.

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

All list items are sentences, example#

When you create an isolated network, the following limitations apply:

  • The isolated network must exist in the same region as the server.

  • You can create up to three isolated networks with up to 64 servers attached to each one.

  • After you create an isolated network, you can’t rename it.

All list items are fragments, example#

The example creates a database instance called myrackinstance with the following characteristics:

  • 512 MB instance flavor

  • Volume size of 2 GB

  • Database named sampledb with a utf8 character set and a utf8_general_ci collation - User named simplestUser with the password password

All list items are imperative statements, example#

You can use Cloud Backup to perform the following actions:

  • Select the files and folders from your server 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, example#

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

  • Rackspace Cloud account. To sign up for a Rackspace Cloud account, go to the Rackspace Public Cloud signup page.

  • Rackspace username and password that you specified during registration.

List that provides terms and more information, example#

You have the following choices for your virtual IP:

  • Public: This setting allows any two servers with public IP addresses to be load balanced. These can be nodes outside of the Rackspace network, but if they are, standard bandwidth rates apply.

  • Shared Virtual IP: Use this setting if you want to load-balance multiple services on different ports while using the same virtual IP address.

  • Private Rackspace network: This is the best option for load-balancing two Cloud Servers because it allows the load-balancing traffic to run on the Rackspace Cloud internal network, called ServiceNet. This option has two distinct advantages: the rate limit is double what the rate limit is on the public interface, and all traffic on the ServiceNet between Cloud Servers is not charged for bandwidth.