User:APaskulin (WMF)/Writing for accessibility

This page is an overview of the parts of the Web Content Accessibility Guidelines (WCAG) that apply to writing documentation.

About the Web Content Accessibility Guidelines

The Web Content Accessibility Guidelines (WCAG) are standards developed by the World Wide Web Consortium (W3C) to make web content more accessible to people with disabilities. This page references version 2.1 of WCAG.

WCAG is organized into principles, guidelines, and success criteria. At the top level, the four principles are: perceivable, operable, understandable, and robust.

In talking about writing, we can focus on principle 3, understandable: Information and the operation of the user interface must be understandable. Within principle 3, guideline 3.1, readable, applies: Make text content readable and understandable. Under guideline 3.1, there are three applicable success criteria:

• 3.1.3 unusual words
• 3.1.4 abbreviations
• 3.1.5 reading level

Unusual words

This criteria states: A mechanism is available for identifying specific definitions of words or phrases used in an unusual or restricted way, including idioms and jargon. Specifically, WCAG calls out nonliteral, specialized, and figurative language. Or said simply, define your terms.

Identifying unusual words

Appropriately, WCAG gives this definition of unusual words:

• Words with multiple dictionary definitions
• Words used in a way not included in a dictionary
• Specialized vocabulary used in a particular profession or field and understood by people in that field but not by people outside the field
• Idiomatic expressions that are accepted by everyone in the region but not by people from other regions where the same language is spoken

Audience and context are key factors in determining whether a word is unusual. Documentation writers should understand the audience of a document to identify which words will be unusual to them.

Avoiding unusual words

When writing documentation for a global audience, best practices require that writers avoid idioms and cultural references. While these types of nonliteral language can be easily removed in most cases, some specialized terms are usually required in most documents.

Defining unusual words

WCAG suggests three main ways of defining unusual words.

Providing inline definitions

This technique adds a definition of the unusual word in the text itself. This is the friendliest way to defining an unusual word, but it comes at the expense of making the text longer. It is often not possible to define every unusual word within a document. However, readers habitually skim past information they don't need, so, with the proper syntactic queues, inline definitions can be easily skipped by readers already familiar with the word.

Linking to definitions

This technique links the first instance of an unusual word to another page with a definition. For example, the first instance of "ssh" on mw:Manual:Installing MediaWiki links to w:Secure Shell. This strategy is familiar to Wikipedia editors and carries over into Wikimedia documentation writing. However, as the English Wikipedia style guide cautions, overlinking can make it difficult to identify links that will aid a reader's understanding.

Providing a glossary

In contrast to linking to definitions, this technique provide a glossary of terms on the same page that the term appears. This option manages cognitive load within the text itself at the cost of visibility.

Abbreviations

This criteria states: A mechanism for identifying the expanded form or meaning of abbreviations is available. In most cases, this criteria can be satisfied by defining an abbreviation the first time it is used on a page. However, in documentation writing, abbreviations can proliferate. The question becomes: When are abbreviations helpful to the reader and when can abbreviations be avoided entirely? For example, it is always better to use "for example" instead of "e.g.".

Consider this text: Request a community ambassador by working with your community relations specialist (CRS) to reach out the manager of community ambassadors. In cases where a team does not have a CRS, they should reach out to their product director or group manager for guidance.

• Is the acronym CRS providing value over using the expanded form?
• If we choose to use the expanded form, should the acronym be included anyways in case readers encounter it elsewhere?
• Does including the acronym require the writer to use it in the rest of the text?
• Is there a point in the text where the context wears off and the acronym needs to be redefined?

In general, documentation writers should avoid abbreviations, including acronyms, whenever possible. As with defining unusual words, it is easier for readers to skim over "community relations specialist" than to remember what "CRS" stands for.

Reading level

This criteria states: When text requires reading ability more advanced than the lower secondary education level after removal of proper names and titles, supplemental content, or a version that does not require reading ability more advanced than the lower secondary education level, is available.

This is the least clear of the criteria that relate the writing. The guidelines do clarify that, to satisfy this criteria, writing should be as clear and simple as possible, using short, common words with fewer syllables and short sentences. They also provide a list of techniques for making text easier to read. However, the authors state that "the WCAG Working Group could not find a way to test whether this had been achieved".