Background

At present, the LXD documentation typically relies on the title attribute in <abbr> HTML elements to provide the expanded form of abbreviations and acronyms. For example, in MyST Markdown, the first sentence of the ZFS storage driver reference is:

{abbr}`ZFS (Zettabyte file system)` combines both physical volume management and a file system.

Rendered as HTML, this becomes:

<abbr title="Zettabyte file system">ZFS</abbr> combines both physical volume management and a file system.

This follows WCAG Technique H28; however, this approach is only an advisory technique rather than a sufficient technique. In fact, the description of technique H28 discourages this approach:

Relying on the title attribute is currently discouraged as many user agents do not expose the attribute in an accessible manner as required by this specification (e.g., requiring a pointing device such as a mouse to cause a tooltip to appear, which excludes keyboard-only users and touch-only users, such as anyone with a modern phone or tablet).

We therefore need an alternative approach to providing the expanded form of acronyms and abbreviations in the LXD documentation.

Task

We can meet the WCAG success criterion for abbreviations by instead following WCAG Technique G97, which is a sufficient technique. Under this technique, we should provide the expanded form of an abbreviation in parentheses after the first occurrence of an acronym on a page. For example:

{abbr}`ZFS` (Zettabyte file system) combines both physical volume management and a file system.

Note that the parentheses now appear outside of the back ticks: when rendered as HTML, the expanded form will now appear directly in the sentence.

Suggested approach

1. Find all abbreviations in the LXD documentation that currently have a title attribute.
2. Update the documentation to instead provide the expanded form in line with the abbreviation or acronym.
   • Note: we should still use the {abbr} role the first time an acronym appears on a page, to simplify discovery of abbreviations in the documentation; we only need to drop the title attribute.
3. Check that the expanded form is only provided the first time that the abbreviation appears on the page.
4. Do a global check for abbreviations across the LXD documentation, and ensure that the expanded form is consistently provided the first time an abbreviation appears on a page.
   • Note: Use your judgment. There may be cases in which a full expansion is not actually required for an abbreviation given the context of that abbreviation and/or the page in the broader documentation set.
5. (optional) Consider other WCAG techniques for abbreviations, determine their applicability to the LXD documentation, and apply those techniques as relevant.

Prerequisites

This issue is beginner friendly. For background, you should:

• Review the {abbr} role in MyST Markdown
• Review the WCAG success criterion for abbreviations
• Review WCAG Technique G97: "Providing the first use of an abbreviation immediately before or after the expanded form"
• (optional) Review other WCAG Techniques for abbreviations provided in the overview of the success criterion
• (optional) Review the Mozilla documentation on <abbr> elements, including best practices for Accessibility

What you will learn

• MyST syntax for roles
• Web Content Accessibility Guidelines (WCAG)

Outcome

The LXD documentation fulfills the WCAG success criterion for abbreviations using a sufficient technique.

Resources

• LXD documentation
• LXD repository
• How to contribute to LXD
• Web Content Accessibility Guidelines (WCAG)
• MyST syntax reference in the Sphinx Stack documentation
• Ubuntu Code of Conduct
• Canonical contributor license agreement
• CODA website.

The mentor for this issue is @elijahgreenstein. They are the Technical Author for LXD.