Quick tip: Formatting unordered lists in plain text

(last update at ) — 485 words

This article is part of a series:

Writing documentation Tips and tricks for writing documentation for code projects.
  1. Why you should and should not write code documentation
  2. Technical documentation writing quick tips
  3. Quick tip: Formatting unordered lists in plain text
  4. Remove hard line breaks from READMEs

Do you use lists in (plain text) prose and Markdown? Check out these simple tips to make them more accessible.

You can improve your list game with just a few tweaks:

  • Use an asterisk instead of a hyphen at the start of a line to make a list item.
  • End each list item with a punctuation mark, for example, a period or semicolon.
  • Do not cram an entire paragraph into a list item.

So this list:

- use an asterisk instead of a hyphen at the start of a line to make a list item
- end each list item with a punctuation mark, for example, a period or semicolon
- do not cram an entire paragraph into a list item

Becomes this:

* Use an asterisk instead of a hyphen at the start of a line to make a list item.
* End each list item with a punctuation mark, for example, a period or semicolon.
* Do not cram an entire paragraph into a list item.

That's it! While this is technically the end of the quick tip, I've added extra information below for those interested.

Why do you want this?

While the benefits of this format are hopefully noticeable to sighted users, it has an even more significant impact on screen reader users.

Take hyphens, for example. Hyphens and dashes are often not pronounced by screen readers because they can make hyphenated words sound unbearable.

While a user can change the configuration to read these characters, they are unlikely to do so for a random (Markdown) article. Meanwhile, asterisks are not as common in writing and are better suited for the task.

The closing punctuation marks will insert a natural pause between sentences, essential for efficient communication.

What about HTML lists?

HTML list items are naturally treated as separate items by sight or screen readers and do not require the same strict formatting.

Note: That is assuming that no one removed the list role from the (un)ordered list by applying list-style-type: none in CSS, which is breaking behavior but also unrelated to the scope of this article.

While there is no strict need to format HTML lists as mentioned above, it is still helpful to do so:

Someone or something may copy HTML and process it as plain text, after which the result might no longer resemble a list. If your list items are proper sentences, then the lack of formatting will not be much of an issue.

Wrap-up

Upgrading the readability of your lists can be done with only two changes:

  1. Use asterisks instead of hyphens to start a list item;
  2. Turn your list items into proper sentences.

This trick can be applied to plain text, HTML, or even real paper. Try it now and see how it improves your texts!

Hat tip to James Scholes, who instructed me on hyphens and who could write a whole essay on this subject.