Tech Writer Style Guide: Using Lists Correctly

What do we want from any user manual? Clarity and consistency. And, good looks. How can we achieve this? Well, as far as looks are concerned, you can start off by reading this article on user documentation design.

And, there’s a long list of things that can be done to improve a user manual’s consistency and clarity. A list, get it? 🙂

General Advice on List Usage

Talking about long lists: how long are they supposed to be? Most tech writers agree that 8 list items is the limit. If you have a list with more than 8 items, think of regrouping them. You can either try uniting some elements into separate lists or transforming some items into sublists.

Another big issue here is inconsistency. The first thing that immediately grabs a reader’s attention is mixed up punctuation. Pay attention to punctuation consistency. If you use a semicolon for the first item, the below items should have it, as well (except for the last one which usually requires a period).

Inconsistency comes in many forms ruining UX. Any UX designer would agree. Make sure you use parallel constructions in your lists. For example:

The new version enables you to:

• add Reviewers to your workflow;
• editing text by adding notes to any part of a help topic.

See the problem? The second item disagrees with the lead-in sentence. The first list item is correct, so the second one should be edited accordingly:

The new version enables you to:

• add Reviewers to your workflow;
• edit text by adding notes to any part of a help topic.

Check out some other practical advice below.

Game of Lists: Bullets vs Numbers

Quite often people just don’t pay enough attention to this. For an average person, a list is just a list whatever the design.

But we, the techcomm folk, can’t be so frivolous with texts – digging deep is part of a technical writer’s job description so to speak.

Knowledge bases and user manuals have to be very clear and easy to reference. Otherwise they can make a situation worse instead of helping. The same way it is for tech support messages.

So, the main rule here is: always use numbered lists when there’s an algorithm described. Feel free to use bulleted lists when you are writing a list of things that can be read in any order (like, a feature list, for example, when your only concern would be placing the more important changes at the top).

What about letters?

Letters work almost like numbers. Although, they still should not be your first choice when describing some steps. Numbers are easier to understand. Use letters for sublists where the order of items is important – this diversity will help a user to read your list and get it faster.

Conclusion

We give this advice quite often, it is simple yet very effective – develop a style guide and stick to it. Companies often have such guides, but they fail to use them consistently. And, nothing looks worse than a dozen help articles in one user manual that have different styles. Try our advice out, and you’ll be well on your way to clear and beautiful technical documentation.

Happy Technical Writing!
ClickHelp Team