Guidelines for creating lists
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.
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.
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.
Previous topic Fictitious information in examples in text, images, and code examples Next topic Creating tutorials