docs(a11y): provide an abbreviation-expansion mechanism (WCAG 3.1.4)

hexajon commented

2026-08-25 19:48:17 +00:00

Owner

The docs lean on a lot of shorthand - CLI, MCP, GPG, TLS, TOFU, ADR, SSH, amd64/arm64 - with no way for a reader to get the expanded form. WCAG 3.1.4 (Abbreviations, level AAA) asks for a mechanism to do that. This is a future accessibility enhancement, not a launch blocker; the site targets AA today.

The constraint that puts this here rather than on the site: the docs render on madtea.lol through syncdocs, and those generated pages are machine-owned. They cannot be hand-patched on the site side, so the mechanism has to live in the docs source, or in a shared transform, so it survives a re-sync.

Options to weigh (not settled):

<abbr title="..."> on first use, from the docs source or a render hook.
A short glossary/terms page, linked site-wide (techniques G62/G55).
A build-time transform that wraps a known list of terms.

Whatever the mechanism, the visible prose stays exactly as written. Expansion is a tooltip, a link, or a first-use gloss, never a rewrite of the copy.

Acceptance:

A reader can find the expansion of each abbreviation used in the docs.
The visible copy and its voice are unchanged.
It applies across the generated docs, so it lives in the source or the transform, not in hand-edited pages.
Meets WCAG 3.1.4.

The docs lean on a lot of shorthand - CLI, MCP, GPG, TLS, TOFU, ADR, SSH, amd64/arm64 - with no way for a reader to get the expanded form. WCAG 3.1.4 (Abbreviations, level AAA) asks for a mechanism to do that. This is a future accessibility enhancement, not a launch blocker; the site targets AA today. The constraint that puts this here rather than on the site: the docs render on madtea.lol through syncdocs, and those generated pages are machine-owned. They cannot be hand-patched on the site side, so the mechanism has to live in the docs source, or in a shared transform, so it survives a re-sync. Options to weigh (not settled): - `<abbr title="...">` on first use, from the docs source or a render hook. - A short glossary/terms page, linked site-wide (techniques G62/G55). - A build-time transform that wraps a known list of terms. Whatever the mechanism, the visible prose stays exactly as written. Expansion is a tooltip, a link, or a first-use gloss, never a rewrite of the copy. Acceptance: - A reader can find the expansion of each abbreviation used in the docs. - The visible copy and its voice are unchanged. - It applies across the generated docs, so it lives in the source or the transform, not in hand-edited pages. - Meets WCAG 3.1.4.

hexajon added the

status/needs-decision

label

2026-08-27 03:57:10 +00:00

hexajon commented

2026-08-27 03:57:10 +00:00

Author

Owner

The docs render on madtea.lol through syncdocs, so the mechanism has to live in the source or a shared transform to survive a re-sync. Three shapes are open: inline <abbr title="..."> on first use, a linked glossary/terms page (techniques G62/G55), or a build-time transform over a known term list. I lean to the glossary page: it is one source-owned file, it survives a re-sync cleanly, it needs no per-page markup churn, and the visible prose stays exactly as written. The <abbr> route touches every first-use across the whole doc set; the transform is the most machinery for a AAA-level item that is not launch-blocking. Which mechanism do you want - say "glossary" and I will build the terms page plus the site-wide link, or name another.

The docs render on madtea.lol through syncdocs, so the mechanism has to live in the source or a shared transform to survive a re-sync. Three shapes are open: inline `<abbr title="...">` on first use, a linked glossary/terms page (techniques G62/G55), or a build-time transform over a known term list. I lean to the glossary page: it is one source-owned file, it survives a re-sync cleanly, it needs no per-page markup churn, and the visible prose stays exactly as written. The `<abbr>` route touches every first-use across the whole doc set; the transform is the most machinery for a AAA-level item that is not launch-blocking. Which mechanism do you want - say "glossary" and I will build the terms page plus the site-wide link, or name another.

hexajon commented

2026-09-08 18:13:44 +00:00

Author

Owner

Decided: a source-owned glossary / terms page, linked site-wide (WCAG techniques G62/G55).

One glossary file lives in the docs source and every generated page links to it. This survives the machine re-sync of the published pages, needs no per-page churn, and leaves the prose unchanged. It satisfies WCAG 3.1.4 without an inline <abbr> sweep across the whole doc set or a new build-time transform.

This stays AAA-level and is not a launch blocker; the site targets AA today.

No governing ADR touches docs accessibility, so this comment is the record.

Decided: a source-owned glossary / terms page, linked site-wide (WCAG techniques G62/G55). One glossary file lives in the docs source and every generated page links to it. This survives the machine re-sync of the published pages, needs no per-page churn, and leaves the prose unchanged. It satisfies WCAG 3.1.4 without an inline `<abbr>` sweep across the whole doc set or a new build-time transform. This stays AAA-level and is not a launch blocker; the site targets AA today. No governing ADR touches docs accessibility, so this comment is the record.

hexajon removed the

status/needs-decision

label

2026-09-08 18:13:45 +00:00

hexajon referenced this issue from a commit

2026-10-21 04:18:52 +00:00

docs: add a glossary of the abbreviations the docs use

hexajon referenced this issue from a commit

2026-10-21 04:18:55 +00:00

docs: cover every doc abbreviation in the glossary and lock it with a test

hexajon referenced this issue from a pull request that will close it,

2026-10-21 04:19:44 +00:00

docs: add a glossary of the abbreviations the docs use #861

hexajon closed this issue

2026-10-21 04:20:15 +00:00

hexajon referenced this issue

2026-10-23 04:35:42 +00:00

docs: remove the glossary and its tests #882

hexajon commented

2026-10-23 04:35:47 +00:00

Author

Owner

I removed the glossary in the issue that this comment links to. The gate test it brought in polices doc prose, which is not this project's job. This issue stays closed as won't-do.

hexajon commented

2026-10-23 04:38:20 +00:00

Author

Owner

The removal is #882.

Rows
Columns

docs(a11y): provide an abbreviation-expansion mechanism (WCAG 3.1.4) #452