How do you use headings and lists to improve the readability and accessibility of your documentation?

1 Why headings matter

Headings are the titles and subtitles of your document. They indicate the structure and hierarchy of your content, and guide the reader's attention and expectations. Headings should be descriptive, concise, and consistent. They should also follow the appropriate level of nesting, meaning that each heading should be subordinate to the one above it. For example, if you use a level 1 heading for the main title, you should use a level 2 heading for the first subtopic, a level 3 heading for the second subtopic, and so on.

2 How to write good headings

To write good headings, you should follow some best practices. First, use clear and specific language that summarizes the main idea of each section. Avoid vague or generic terms that could confuse or mislead the reader. Second, use parallel structure and consistent formatting for headings of the same level. For example, if you use a verb phrase for one level 2 heading, use a verb phrase for all level 2 headings. Third, use keywords that match the reader's search intent and the document's purpose. For example, if you are writing a tutorial, use words like "how to", "steps", or "guide". If you are writing a reference, use words like "overview", "parameters", or "examples".

3 When to use lists

Lists are another way to organize and present your content. They help you break down complex or lengthy information into smaller and manageable chunks. They also help you emphasize important or related points, and create visual contrast and variety in your document. You should use lists when you want to show a sequence, a hierarchy, or a collection of items. For example, you can use a list to show the steps of a procedure, the categories of a concept, or the features of a product.

4 How to format lists

To format lists, you should follow some basic rules. First, choose the right type of list for your content. There are two main types of lists: ordered and unordered. Ordered lists use numbers or letters to show the order or priority of the items. Unordered lists use bullets or symbols to show the items without any order or priority. Second, use consistent punctuation and capitalization for each item. For example, if you use a period at the end of one item, use a period at the end of all items. Third, use parallel structure and clear wording for each item. For example, if you use a noun phrase for one item, use a noun phrase for all items.

5 How to nest lists

Sometimes, you may need to nest lists, meaning that you create a list within a list. This can help you show more details or subcategories of an item. To nest lists, you should indent the nested list under the parent item, and use a different type of list marker. For example, if you use a numbered list for the parent list, you can use a bulleted list for the nested list. You should also avoid nesting more than two levels deep, as this can make your document look cluttered and confusing.

6 How to test your headings and lists

After you write your headings and lists, you should test them for readability and accessibility. You can do this by using some tools and techniques. First, you can use a readability tool, such as Hemingway Editor or Readable, to check the readability score and grade level of your document. You should aim for a score of 60 or higher, and a grade level of 8 or lower. Second, you can use a screen reader, such as NVDA or VoiceOver, to listen to how your document sounds to people with visual impairments. You should check if your headings and lists are clear, logical, and easy to follow. Third, you can use a checklist, such as the one from Write the Docs, to review your headings and lists for consistency, accuracy, and completeness.

7 Here’s what else to consider

This is a space to share examples, stories, or insights that don’t fit into any of the previous sections. What else would you like to add?