Lists

Lists provide for greater readability and user orientation, and are commonly used in documentation.

In This Article

• General
• Types
• Guidelines

General

• The list type indicates the sort of information it provides to the user. For example, numbered lists indicate a sequence of actions while bulleted lists introduce items of the same priority.
• The structure, formatting, and punctuation of a list add up to the quality of the content and need to follow specific rules.
  

Types

• Numbered list items start with a number. Use them when you describe steps for a sequence of actions and procedures.
• Bulleted list items start with a bullet. Use them when the priority of each list items is the same. For example, unordered series of concepts, items, or options, as well as instructions that are not sequential.

Guidelines

• Introduce a list with one or more sentences and end them with a colon. Avoid using fragments.

  Not that good	Much better
  The following rules apply. These are the rules— The rules:	The following rules apply:

• Start each bullet with an uppercase letter. Exceptions are allowed when you need to preserve the casing.

  Not that good	Much better
  Apply any of the following approaches: updating the app reinstalling the app removing the app completely, clearing the cache, and installing it again	Apply any of the following approaches: Updating the app Reinstalling the app Removing the app completely, clearing the cache, and installing it again
  The LiveSync JavaScript API provides the following methods: Enable()—Enables LiveSync with the three-finger refresh gesture. Disable()—Disables LiveSync with the three-finger refresh gesture. Sync()—Forces LiveSync, even if the LiveSync three-finger refresh gesture is disabled programmatically.	The LiveSync JavaScript API provides the following methods: enable()—Enables LiveSync with the three-finger refresh gesture. disable()—Disables LiveSync with the three-finger refresh gesture. sync()—Forces LiveSync, even if the LiveSync three-finger refresh gesture is disabled programmatically.

• End each bulleted line with a period if the line is a complete sentence. If any list item requires a period, add periods to all the items even though they might not all be complete sentences.

  Not that good	Much better
  Apply any of the following approaches: Reinstall the app Update the operating system Remove the app completely, clear the cache, and install it again.	Apply any of the following approaches: Reinstall the app. Update the operating system. Remove the app completely, clear the cache, and install it again.

• Avoid using articles in the beginning.

  Not that good	Much better
  A List of Desktop Widgets	List of Desktop Widgets

• Apply uniform, parallel structures whenever possible—if the first list entry starts with an infinitive, start each of the other bullets in the list with an infinitive.

  Not that good	Much better
  Apply any of the following approaches: App update. Reinstalling the app. Remove the app completely, clear the cache, and install it again.	Apply any of the following approaches: Update the app. Reinstall the app. Remove the app completely, clear the cache, and install it again.

• Move as much of the repeating bullet content as possible to the introductory sentence.

  Not that good	Much better
  In this version: You can debug on iOS devices. You can develop with Apache Cordova 4.0.0. You can distribute minor app updates over the air.	In this version, you can perform the following tasks: Debug on iOS devices. Develop with Apache Cordova 4.0.0. Distribute minor app updates over the air.

• If the list is more than three levels deep, restructure it.

• Avoid creating one-item lists. Exceptions are allowed for one-step procedures, multiple lists where some of them contain a single item (for parallelism), links.

• In a list, first state the action, then any other things.

  Not that good	Much better
  Refer to the article on styles and layout if you want to see the full list of web font icons in Kendo UI.	To see the full list of web font icons in Kendo UI, refer to the article on styles and layout.

• Try to use just one sentence in a list item. If you need to state additional information, use a second paragraph in the same list item.

• If the step specifies a context, start the sentence with it.

  Not that good	Much better
  1. Locate and tap your newly deployed app in the My Watch view.	1. In the My Watch view, locate and tap your newly deployed app.

• If the step includes a condition, start the sentence with it.

  Not that good	Much better
  1. Select iOS > Cryptographic Identities if you want to export an iOS cryptographic identity.	1. If you want to export an iOS cryptographic identity, select iOS > Cryptographic Identities.

• (For definition lists) Use an em dash (— in Markdown or HTML) as a separator. Do not use spaces around the em dash. If the definition list has more than three items, consider using a table.

• If you need to include an explanation or a clarification, place it in a separate paragraph aligned with the text in the list element.

  Not that good	Much better
  You can integrate the DateInput with: DatePickers. DatePickers enable users to enter or pick a date. DateTimePickers TimePickers	You can integrate the DateInput with: DatePickers DatePickers enable users to enter or pick a date. DateTimePickers TimePickers