Lists

Lists organize information and help users locate the details they need. When possible, use lists in your documentation to break down large chunks of text.

tip

For instructions on implementing this guidance with Markdown, refer to Confluence: Formatting documentation.

Note: This guidance pertains to unordered (bulleted) lists and some ordered (numbered) lists. For guidance on lists of instructions, refer to Procedures.

Introductory text

Introduce each list with a stem sentence that makes the purpose of the list clear. Use a complete sentence followed by a colon. You can use "the following" or "as follows" to refer to the list items and complete the sentence.

Don't use an incomplete sentence as the stem, followed by a list of items that complete the sentence. These constructions are difficult to translate.

Don't follow a heading with a list. Always include a stem sentence in regular text.

Parallel construction

Use the same type of grammatical construction and part of speech for each list item. For example, items can be noun phrases or complete sentences. Don't mix complete and incomplete sentences, or different parts of speech, in the same list.

Incorrect	Correct
The texture format to use depends on the type of Light: For directional and spot lights, use a 2D texture. Use cubemap textures for point lights.	The texture format to use depends on the type of Light: Directional: 2D texture Spot: 2D texture Point: cubemap texture

Capitalization and punctuation

Start each item in the list with a capital letter.

Use punctuation consistently within each list. If the items are complete sentences, end each item with a period.

Don't use semicolons or commas at the end of list items, or punctuate an entire list as if it were one sentence.

Incorrect	Correct
The database owner can: create and delete a database; add, delete, or modify a document; and add, delete, or modify any information in the database.	The database owner can perform the following actions: Create and delete a database. Add, delete, or modify a document. Add, delete, or modify any information in the database.
The Transform component contains three sets of coordinates: scale. position. rotate.	The Transform component contains three sets of coordinates: Scale Position Rotation

Descriptions in lists

If your list contains noun phrases and their descriptions (for example, a list of settings and their functions), use a colon to set the description off from the noun phrase. Don't bold the text before the colon.

Incorrect	Correct
You can find the database files in the following locations: Find the Source Asset Database in Library\SourceAssetDB Artifact Database in Library\ArtifactDB	You can find the database files in the following locations: Source Asset Database: Library\SourceAssetDB Artifact Database: Library\ArtifactDB