Skip to main content


         This documentation site is for previous versions. Visit our new documentation site for current releases.      
 

Guidelines for creating lists

Updated on January 21, 2021

Organize information into lists when appropriate for enhanced clarity and brevity.

Depending on the type of information that you want to present, you can use the following types of DITA lists:

  • Unordered list
  • Ordered list
  • Definition list

Unordered list

Use a bulleted list for an unordered series of concepts, items, or options. Each list item can be a single word, multiple words, a sentence fragment, or a complete sentence. The list must have at least two items; otherwise it is not a list. When you create an unordered list, consider the following guidelines:

  • Introduce the list with either a clause or a complete sentence that ends with a colon.
  • Capitalize the first word in each item in the list.
  • Make sure that the list items are grammatically parallel. For example, if the first item in a list begins with an imperative verb, begin all the items in the list with an imperative verb.
  • Arrange the list items in a logical way. If there is no better method for arranging the list items, put them in alphabetical order.
  • Do not include a period at the end of a list item if the list item is not a complete sentence. However, if the list items are a mixture of fragments and complete sentences, end each list item with a period.
  • Use <ul> and <il> tags to create an unordered list.
For example: The database owner can do the following actions:
  • Create and delete a database
  • Add, delete, or modify a document
  • Add, delete, or modify any information in the database
For example: Use linked files when these criteria are met:
  • You will use the same computer to create and display your presentation.
  • Your files are larger than 100 KB.
  • You plan to make changes to the source files.

Ordered list

Use an ordered list for procedures or for other information in which the sequence or the priority is important. Each list item can be a single word, multiple words, a sentence fragment, or a complete sentence. The list must have at least two items; otherwise it is not a list. When you create an ordered list, consider the following guidelines:

  • Introduce the list with a complete sentence that ends with a colon.
  • Make sure that the list items are grammatically parallel. For example, if the first item in a list begins with an imperative verb, begin all the items in the list with an imperative verb.
  • Capitalize the first word in each item in the list.
  • Do not include a period at the end of the list item if the list item is not a complete sentence. However, if the list items are a mixture of fragments and complete sentences, end each list item with a period.
  • Use <ol> and <il> tags to create an ordered list.

Definition list

Use a definition list (what Microsoft Style refers to as a term list or term-def list) for a set of terms, concepts, parameters, fields, or similar items that are followed by a brief definition, description, or explanation. When you create a definition list, consider the following guidelines:

  • Introduce the list with a complete sentence that ends with a colon.
  • Do not include punctuation after the term.
  • Capitalize the term and the first word of the definition.
  • Use either a sentence fragment or a complete sentence for the definition.
  • Include a period at the end of the definition if it is a sentence fragment or a complete sentence.
  • Use <dl> and <dlentry> tags to create a definition list.
For example: You need to provide the following details:
Computer name
The name by which the local area network identifies a server or workstation. Each computer name on the network must be unique.

Exceptions to Microsoft Style

Do not use “the following:” at the end of an introductory sentence without a noun after “the following.” Microsoft Style allows this usage, as well as the use of sentence fragments to introduce lists, but for (eventual) translation purposes, we do not follow this guideline.

Although Microsoft Style allows for lists to include sentence fragments that complete the introductory sentence for the list, Microsoft Style also notes translation considerations: “Be aware that the grammar and syntax of different languages can make it difficult to match the structure in English of an introductory fragment that is completed by each list element. Introductory fragments may also lead to mistranslation in content that is machine translated.” For this reason, it’s best to avoid this type of list structure.

Have a question? Get answers now.

Visit the Support Center to ask questions, engage in discussions, share ideas, and help others.

Did you find this content helpful?

Want to help us improve this content?

We'd prefer it if you saw us at our best.

Pega.com is not optimized for Internet Explorer. For the optimal experience, please use:

Close Deprecation Notice
Contact us