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.
For punctuation guidelines, follow the Microsoft Writing Style Guide, which includes considerations for localization.
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.