w3c / w3c/maturity-model

Avoid abbreviations with a title attribute

Open Beginner friendly
#369 0 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
HTML
Stars
26
Forks
9
Avg merge
57m
Merged PRs (30d)
2

Description

A best practice for abbreviations is expanding them on first use.
Instead, the old practice to use an <abbr> element with a title attribute to expand the abbreviation is generally not recommended any longer because it's not accessible for everyone:

  • It doesn't work for keyboard users.
  • It doesn't work on touch devices (mobile).
  • It is scarcely supported by browsers / screen readers combinations.

In the very first paragraphs of the Accessibility Maturity Model group note I could find a mixed use of the two patterns above, which also triggers a consistency issue:

  • Correct: Accessibility Maturity Model (AMM)
  • Not recommended: <abbr title="Non-Governmental Organization">NGO</abbr>
  • Not recommended: <abbr title="Small Office Home Office">SOHO</abbr>
  • Not recommended: <abbr title="Human Resources">HR</abbr>
  • More occurrences.

Many users can't access the expansion of these abbreviations. I'd like to suggest avoiding the usage of <abbr> + title altogether and expand on first use instead.

The only case in this document where abbr + title is maybe acceptable is <abbr title="World Wide Web Consortium">W3C</abbr> but that's only because most people reading this document already know what 'W3C' stands for.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by locating the Accessibility Maturity Model group note and search its opening paragraphs and remaining occurrences for elements with title attributes. Replace the cited abbreviations with expansions on first use, then verify that the document consistently avoids this pattern while preserving the intended wording.

Written by the indexing model from the issue text.

Assessment

Tech stack
html
Domain
accessibility, documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
72/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.