Lists are a great way to break down complex ideas and make them easier to read and scan.

### Best practice

- Bulleted lists should contain relatively few words or short phrases. For most content types, limit the number of items in a list to five.
- Don’t add commas (,) or semicolons (;) to the ends of list items.
- Some content types may use bulleted lists that contain 10 items, but it's preferable to break longer lists into several lists, each with its own subheading or introduction.
- Never create a bulleted list with only one bullet, and never use a dash to indicate a bulleted list.
- If your list items are fragments, capitalize the list items for ease of scanning but don't use terminal punctuation. 
Example:
    
    I went to the shops to buy:
    
    - Milk
    - Flour
    - Eggs
- Make sure all your list items are parallel. This means you should structure each list item in the same way. They should all be fragments, or they should all be complete sentences. If you start one list item with a verb, then start every list item with a verb.
- Every item in your list should start with a capital letter unless they’re parameters or commands.
- Nested sequential lists are labeled with lowercase letters. For example:
    1. Top level
    2. Top level
        1. Child step
        2. Child step

## Numbers

When you work with numbers in content, the best practices include:

- Spell out the numbers one to nine, except in units of measure such as 4 MB.
- Represent numbers with two or more digits as numerals (10, 625, 773,925).
- Recast a sentence, rather than begin it with a number (unless it's a year).
- When you cite numbers in an example, write them out as they appear in any accompanying screenshots.
- Write numbers out as they appear on the platform when you cite them in an example.
- To refer to large numbers in abstract (such as thousands, millions, and billions), use a combination of words and numbers. Don't abbreviate numeric signifiers.
- Avoid using commas in numbers because they can represent decimals in different cultures. For numbers that are five digits or more, use a space to separate.
    
    
    | Correct | Incorrect |
    | --- | --- |
    | 1000 | 1,000 |
    | 14 586 | 14,586 |
    | 1 390 680 | 1,390,680 |

### Versions

When writing version numbers for release notes, use the following example:

- version 4.8.2
- v1.0
- Docker Hub API v2

## Punctuation

### Colons and semicolons

- Use colons to: introduce a list inline in a sentence; introduce a bulleted or numbered list; and provide an explanation.
- Don't use semicolons. Use two sentences instead.

### Commas

- Use the serial or Oxford comma - a comma before the coordinating conjunction (and, or) in a list of three or more things.
- If a series contains more than three items or the items are long, consider a bulleted list to improve readability.

### Dashes and hyphens

- Use the em dash (-) sparingly when you want the reader to pause, to create parenthetical statements, or to emphasize specific words or phrases. Always put a space on either side of the em dash.
- Use an en dash (-) to indicate spans of numbers, dates, or time.
- Use a hyphen to join two or more words to form compound adjectives that precede a noun. The purpose of joining words to form a compound adjective is to differentiate the meaning from the adjectives used separately (for example, ‘up-to-date documentation’ ‘lump-sum payment’, and ‘well-stocked cupboard’. You can also use a hyphen to:
    - Avoid awkward doubling of vowels. For example ‘semi-independence*’,* or ‘re-elect’.
    - Prevent misreading of certain words. For example ‘Re-collect’ means to collect again; without a hyphen the word recollect has a different meaning.

### Exclamation marks

Avoid the use of exclamation marks.

### Parentheses

Don't use parentheses in technical documentation. They can reduce the readability of a sentence.