Writing should be usable

October 1, 2024

Writing in digital systems is usable when it is accessible, navigable, clear, and concise.

You can try some activities to help make your writing more usable.

Note: This article refers extensively to Web Content Accessibility Guidelines Success Criteria (SC) and techniques.

Usable writing is accessible

Writing is accessible if readers have the ability to distinguish the content in a text and perceive it as words and concepts. We can use text alternatives, color, text resize, and layout to help users read the text.

Text alternatives

Images and visualizations that convey information should have a text description. Audio and video should have captions, descriptions, and transcripts.

For example, the alternative text for the image tomatoes.jpg could describe the quantity (“cluster”), quality (“ripe”), type (“cherry”), and location (“community garden”) of the subject (“tomatoes”). It is more rich in meaning than if the alternative text was merely a statement of the subject (“Tomatoes”).

<!-- Rich description -->
<img src="tomatoes.jpg" alt="A cluster of ripe
	cherry tomatoes grows in a community garden">

<!-- Poor description -->
<img src="tomatoes.jpg" alt="Tomatoes">

<!-- Missing description -->
<img src="tomatoes.jpg">

These text alternatives also help those who do not use assistive technology, such as a screen reader or braille display. For example, those who are not hard of hearing can still benefit from captions when in a noisy room or in a situation in which they are trying to be quiet.

See: SC 1.1.1

Color

Don’t just use color as the only way to distinguish content.

For example, someone who is colorblind may need more than just text colored red to understand what fields in a form is required.

Required fields are displayed in red

Complement color with some visual redundancy like a symbol or unique background pattern.

Required fields are displayed in red and marked with an asterisks (*)

Text should have sufficient contrast against its background. You can use browser dev tools to discover low-contrast text.

See: SC 1.4.1, SC 1.4.3, SC 1.4.6

Text resize

You should be able to resize text upwards of 200%, but it should be done in a way that no information or functionality is lost. This can happen when images overlap text or text is clipped.

See: SC 1.4.4

Layout

To improve typographical layout, aim for:

• Line length: 80 characters or less
• Line spacing: 150% or more
• Paragraph spacing: 250% or more
• Text alignment: Not justified

Scrolling in two directions is tricky, so try to avoid it. This gets challenging with content like tables, but there are techniques that you can further research which help. Since scrolling primarily happens vertically, try to make the content adaptable enough so it averts horizontal scrolling when the device is small (such as 320px wide).

Don’t cut off or overlap text. This can can happen when the user zooms in or sets custom styles in the browser.

See: SC 1.4.8, SC 1.4.10, SC 1.4.12

Usable writing is navigable

When landing on a webpage, you need to get oriented, move around, and navigate to other pages. This can be done with page titles, headings, landmarks, and links.

Page title

The page title is the first piece of content presented to a user. This is what is displayed on a browser tab.

Page titles typically consistent of multiple parts. It starts with a description of the page, gets more broad, and eventually labels the brand name of the site. That first part usually should match the primary heading of the page (<h1>).

The parts should be separated with some character, such as a dash (-), pipe (|), or bullet (·).

See: SC 2.4.2

Headings

Headings should start with the <h1> element (“heading level 1”). The heading levels should stay consistent, in the right order and not skipped. They should proceed the content it describes. Its description should be relevant for its content. It should be succinct.

<h1>Garden plants</h1>

<h2>Pepper</h2>
<!-- Pepper-related content -->

<h2>Squash</h2>
<!-- Squash-related content -->

See: SC 2.4.6, SC 2.4.10

Landmarks

Many HTML elements have an implicit meaning. They are “landmark” elements which means they help users of assistive technology to navigate a page. It helps them to skip to major sections of content, like the header/banner at the start of the page, the main content area, or the footer at the end of the page.

Landmarks should be labeled when there are multiple landmarks of the same kind on a page. This makes them distinct.

In the following example, there are two areas of navigation. The primary navigation doesn’t have a visible label, so the attribute aria-label is used to just explicitly label it as “primary” for assistive technology users. The second navigation has the visible label “On this page” as a heading level 2. In this case, the nav’s label is determined by using the aria-labelledby attribute, referencing the heading. The main element doesn’t need a label, because there should ever only be one of those.

<nav aria-label="Primary">…</nav>
<main>
	<h1>…</h1>
	<nav aria-labelledby="nav1">
		<h2 id="nav1">On this page</h2>
		…
	</nav>
	…
</main>

See: SC 2.4.1, Technique ARIA11

Links

The links used in “On this page” navigation are examples of skip links. They jump the page to another section of content. Skip links are also used at the start of a page, so that a keyboard user has the option to, for example, skip to the main content. This is useful for when someone is already familiar with the header/banner at the start of all the pages on a site. These skip links are typically visually hidden until they have keyboard focus.

<a href="#main">
	Skip to main content
</a>

A person should understand the purpose of a link by its surrounding context. However, links can be better if written such that the surrounding context is not needed.

For example, the link “learn more” requires the nearby text “about grow bag gardening” to understand what it is about.

It is better to simply have the link text “grow bag gardening.”

For this next example, the text says “Tap the Search icon in the upper nav”. There is no link. You have to guess what it means, and hopefully you already noticed the search icon elsewhere on the page.

It is better to write “Use Search to find gardening tutorials”. “Search” is a link to start a new search. “Gardening tutorials” is a link to the search results for gardening tutorials. That text is also an example of what to search for.

See: SC 2.4.1, SC 2.4.4, SC 2.4.9

Usable writing is clear

Improving clarity and using plain language is not dumbing down the content. It is opening it up to wider audience.

We can make our writing more clear by paying attention to language, unusual words, pronunciation, reading level, and consistency.

Language

All pages should define the primary language of its text by using the lang attribute on the <html> element. In the case of English language content, use the en value. This helps text-to-speech software more accurately pronounce content.

<html lang="en">

Where subsets of text differ from the page’s primary language, use a different lang value on the containing element.

<!-- German -->
<p lang="de">Deutsch</p>

<!-- Italian -->
<p lang="it">Italiano</p>

<!-- French -->
<p lang="fr">Français</p>

See: SC 3.1.1, SC 3.1.2

Unusual words

There are many categories of words that we use which may be challenging for someone to understand, such as:

• Multiple definitions (“gig”)
• Jargon (“code blue” is for medical professionals)
• Slang (“shiner” is a black eye)
• Idioms (“hot potato” is a controversial issue)
• Acronyms (“ROI” means Return On Investment)
• Abbreviations (“lb.” means pounds)

These words should be defined so users know what they mean in the given context. Or even better, the content could be written so these words are never needed.

Where a word is defined inline on a page, wrap the word in a <dfn> (“definition”) element. In this example, the text is “A basil plant is an aromatic annual herb of the mint family” and “basil plant” is wrapped in the <dfn> element.

<p>A <dfn>basil plant</dfn>
is an aromatic annual herb
of the mint family.</p>

Definitions can also be curated in a glossary. Words can be linked to the terms on the same page or another page. In this example, the word “basil” links to its definition in a glossary section near the end of the page. The <dl> (“description list”) element is the appropriate container to use for a set of key-value pairs. The link references the <dt> (“description term”) element.

<p>…<a href="#def-basil">basil</a>…</p>
<h2>Glossary</h2>
<dl>
	<dt id="def-basil">Basil</dt>
	<dd>…</dd>
</dl>

Abbreviations can be defined or expanded inline. For the following example, the rest of the page can freely use the abbreviations “IU” and “GPA” because they have been declared.

First-year applicants of Indiana University (IU) must have a minimum GPA (grade point average) of 2.5.

Abbreviations can be declared with the <abbr> element. In the following example, “IU v. OSU” contains three abbreviations which can be individually expanded to mean “Indiana University verses Ohio State University.”

<abbr title="Indiana University">
	IU
</abbr>
<abbr title="verses">v.</abbr>
<abbr title="Ohio State University">
	OSU
</abbr>

See: Technique H54, Technique G55, Technique G97, Technique H28

Pronunciation

Some words can be troublesome to pronounce. Like unusual words, their pronunciation can be expanded inline or linked to.

For example, at Indiana University, the NameCoach tool allows students to record themselves speaking their name. This can be listened to in Canvas (a learning management system), so the instructor or classmates can know how to properly speak their name.

See: SC 3.1.6

Reading level

If you know your audience, then you should know how to write for them, using the language they know.

For example, if your audience is alumni, you know they have a college reading level, and they will have the experience of going through an academic institution.

If you are writing for general audiences, use common words, short words, and short sentences. This also helps readers with cognitive impairments or those in which English is not their primary language. This writing should be at a middle school reading level (grades 7, 8, 9).

Note: There are readability tests that can be used to help reduce the reading level. However, they are predictions not guarantees of how understandable any given text is.

See: SC 3.1.5

Consistency

Use words consistently and predictably.

For example, if the search field in the website’s header does the same thing on every page, the submit button should be labeled the same way on all those pages. Don’t label it “Search” on one page, “Find” on another page, and “Go” on a third page.

However, if making the text consistent reduces clarity, then it is better to be inconsistent.

See: SC 3.2.4

Usable writing is concise

A person says aloud 120 to 150 words per minute on average. In contrast, screen reader users commonly configure their reading speed to be several times faster.

Given this, extra content is okay if it is needed to be clear.

When clarity is no longer the issue, then be concise: Shorten content. Break up content. Disclose content.

Shorten content

Look for useless information. Limit the purpose of a page, to limit the information needed. This will clarify the particular context, facts, and requirements that should be displayed on any given page. If it doesn’t help the user accomplish their purpose for visiting a page, it is a distraction that should be removed.

Many prepositional phrases can be shortened with fewer words. For example:

Some adverbs don’t add value and can generally be eliminated, such as: definitely, extremely, really, truly, and very.

Use active voice instead of passive voice. This will clarify the responsibilities of the subject in the sentence with pronouns and sometimes shorten the sentence length. For example:

Break up content

Break up long blocks of content to make it easier to skim and understand:

• Break up sentences containing long lists into into bulleted lists.
• Break up similar data points into tables.
• Break up long paragraphs into multiple paragraphs.
• Break up related content into sections with headings.

Disclose content

Some content may be helpful to some users but an annoyance to other users. Allow users to opt in to seeing additional content with accordions, disclosures, or links.

Activities for usable writing

The following are four solo and research activities for making your writing more usable. Follow this format:

1. Conduct the activity.
2. Analyze the results.
3. Adjust the content.
4. Try the activity again to confirm there was improvement.

Read aloud (solo)

Read aloud content to see how natural the writing sounds. If it sounds odd or unnatural, then change the wording and try again.

Readability testing (solo)

The Hemingway Editor is a tool that suggests how to simplify the reading level of a text sample. As you type, it will highlight adverbs, use of passive voice, and long sentences. The paid version helps you make corrections with artificial intelligence.

Paraphrase testing (5 to 9 participants)

Conduct paraphrase testing to understand how participants interpret or misunderstand the content. Participants should:

• read a section of content
• paraphrase the content in their own words

Content testing (5 to 9 participants)

Conduct content testing to evaluate the helpfulness of content. Participants should:

• circle content that is helpful
• underline content that is confusing or not helpful