8 Lists

8.1 Use lists with similarly structured items for complex text (ASM-8)

  • Use lists instead of long sentences to present complex text in a way that is easier to read and understand.

  • The list items shall be a set of similarly structured items. For example, each item should be a noun or a phrase that starts with a verb.

Exceptions

There are no exceptions.

Example

Code

The outline of the road marking is described by the attributes @length and @space:

* @length represents the visible part of the line.
* @space describes the non-visible part.

Result

The outline of the road marking is described by the attributes @length and @space:

  • @length represents the visible part of the line.

  • @space describes the non-visible part.

Source

8.2 Use AsciiDoc syntax for lists (ASM-48)

Exceptions

There are no exceptions.

Example

Code

Unordered list

* This is an item.
* This is another item.
* This is an additional item.

Ordered list

. This is the first item.
. This is the second item.
. This is the third item.

Result

Unordered list

  • This is an item.

  • This is another item.

  • This is an additional item.

Ordered list

  1. This is the first item.

  2. This is the second item.

  3. This is the third item.

Source

8.3 Choose a suitable type of list (ASM-10)

8.3.1 Use a bulleted list for things that have something in common but do not need to appear in a particular order

Exceptions

There are no exceptions.

Example

Code

The database owner can:

* Create and delete a database
* Add, delete, or modify a document
* Add, delete, or modify any information in the database

Result

The database owner can:

  • Create and delete a database

  • Add, delete, or modify a document

  • Add, delete, or modify any information in the database

Source

Microsoft Style Guide: docs.microsoft.com/en-us/style-guide/scannable-content/lists#bulleted-lists

8.3.2 Use a numbered list for sequential items (like a procedure) or prioritized items (like a top 10 list)

Exceptions

There are no exceptions.

Example

Code

To sign on to a database:

. Select menu:File[Open database].
. Under 'Username', enter your name.
. Under 'Password', enter your password, and then select btn:[OK].

Result

To sign on to a database:

  1. Select File  Open database.

  2. Under 'Username', enter your name.

  3. Under 'Password', enter your password, and then select OK.

Source

Microsoft Style Guide: docs.microsoft.com/en-us/style-guide/scannable-content/lists#bulleted-lists

8.3.3 Use a description list for terms and definitions or abbreviations and the full forms

Exceptions

There are no exceptions.

Example

Code

ASAM::
Association for Standardization of Automation and Measuring Systems

XML::
Extensible Markup Language

Result

ASAM

Association for Standardization of Automation and Measuring Systems

XML

Extensible Markup Language

Source

ASAM specific rule.

8.4 Start each list item in a list with an uppercase letter (ASM-5)

Exceptions

If a list item starts with one of the following, do not use an uppercase letter:

  • Code elements, for example:
    <elevation> elements shall be defined in ascending order according to the s-coordinate.

  • Mathematical signs, for example:
    x and y

  • URLs, for example:
    www.asam.net

Example

Code

* This is the first sentence.
* This is the second sentence.
* This is the third sentence.

Result

  • This is the first sentence.

  • This is the second sentence.

  • This is the third sentence.

Source

ASD-STE100 (2021, issue 8, ASD Simplified Technical English, ASD-STE100, is a Copyright and a Trade Mark of ASD, Brussels, Belgium): Rule 4.3 Use a vertical list for complex text, page 1-4-4

8.5 Put a full stop at the end of a list item if it is a full sentence (ASM-6)

Exceptions

There are no exceptions.

Example

Table 40. Use of full stops at the end of a list item
No Yes

  • This is the first sentence

  • This is the second sentence

  • This is the third sentence

  • This is the first sentence.

  • This is the second sentence.

  • This is the third sentence.

Rule ASM-11 contains an example where punctuation is prohibited.

Source

8.6 Do not put punctuation or conjunctions at the end of a list item if it is not a full sentence (ASM-11)

If an item in a list is not a full sentence, then do not put the following punctuation or conjunctions:

  • Full stops (periods)

  • Semicolons

  • Commas

  • Conjunctions like "and" or "or"

Exceptions

There are no exceptions.

Example

Table 41. Use of punctuation and conjunctions at the end of an item
No Yes

  • Common junctions,

  • Direct junctions, and

  • Virtual junctions.

  • Common junctions

  • Direct junctions

  • Virtual junctions

Source