Lists are a powerful way to organize information, but they don't always make for a pleasant reading experience. Keep these points in mind when you're writing a list:
- Always capitalize the first letter of the first word in each list item.
- Use ordered (numbered) lists for step-by-step procedures, where the order matters.
- Use unordered (bulleted) lists to make it easier for users to skim related information.
- Use OR on a separate line when there is more than one option for a numbered step or a bullet point.
- Use tables when your ordered or unordered list would benefit from some extra detail.
Tip
For punctuation guidelines, follow the Microsoft Writing Style Guide, which includes considerations for localization.
In-line lists
As an alternative to using bullet point lists, you can do an in-line list, like this: C SDK | Go | Java.
You might want to use an in-line list when:
- You're linking to further documentation.
- Customers will likely be selecting a single option.
- The list item can be displayed with a short word or phrase (like Java, or Infrastructure).
- You think a bullet point list takes up a lot of vertical space. This may happen in circumstances where a procedure must include several lists. Here's one example of this.
- There are only two or three potential options they'll be choosing from and a bullet point list seems unnecessary. Here's an example.