sixfold-space/madtea

SHA256

Fork 0

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

Merged

hexajon merged 3 commits from issue-452-docs-glossary-abbreviations into main

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

hexajon commented

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

Owner

Summary

What was wrong

The docs use many abbreviations (CLI, MCP, ADR, GPG, TLS, TOFU and more). A reader had no way to find the full form of one. WCAG 3.1.4 asks for such a mechanism.

What changed

I chose a glossary page. It lives in the docs source, so a re-sync of the published pages keeps it. The visible prose stays as written.

docs/GLOSSARY.md is new. It has one table with three columns: term, expansion, meaning. Terms are in alphabetical order. It covers the abbreviations used in the docs, including license IDs, signal names, PKCE, SQL, and others. OMP has its full form, Oh My Pi. The entry for GPG says the install script runs GPG, not madtea.
docs/README.md has a new "Terms" section that links the glossary.
README.md has one sentence that links the glossary.

Tests

TestGlossary in internal/docs/glossary_test.go checks that each table row has three filled cells and that no expansion is only a command name. It checks that terms are in alphabetical order with no duplicates and that the file has no em-dash. It also checks that both README.md and docs/README.md link the glossary.
TestGlossaryCoversDocAbbreviations in internal/docs/glossary_coverage_test.go reads the prose of README.md, CONTRIBUTING.md, SECURITY.md, CODE_OF_CONDUCT.md, THIRD-PARTY-LICENSES.md, and every .md file under docs/. It removes code blocks, code spans, comments, link targets, and URLs. It then finds each all-caps token of two or more letters. Each token must have a glossary row or be in the notAbbreviations list of words that are not abbreviations. The test also fails if a word is in both places.

Refs #452

./scripts/gate.sh passes on this commit.

Closes #452

## Summary ## What was wrong The docs use many abbreviations (CLI, MCP, ADR, GPG, TLS, TOFU and more). A reader had no way to find the full form of one. WCAG 3.1.4 asks for such a mechanism. ## What changed I chose a glossary page. It lives in the docs source, so a re-sync of the published pages keeps it. The visible prose stays as written. - `docs/GLOSSARY.md` is new. It has one table with three columns: term, expansion, meaning. Terms are in alphabetical order. It covers the abbreviations used in the docs, including license IDs, signal names, PKCE, SQL, and others. OMP has its full form, Oh My Pi. The entry for GPG says the install script runs GPG, not madtea. - `docs/README.md` has a new "Terms" section that links the glossary. - `README.md` has one sentence that links the glossary. ## Tests - `TestGlossary` in `internal/docs/glossary_test.go` checks that each table row has three filled cells and that no expansion is only a command name. It checks that terms are in alphabetical order with no duplicates and that the file has no em-dash. It also checks that both `README.md` and `docs/README.md` link the glossary. - `TestGlossaryCoversDocAbbreviations` in `internal/docs/glossary_coverage_test.go` reads the prose of `README.md`, `CONTRIBUTING.md`, `SECURITY.md`, `CODE_OF_CONDUCT.md`, `THIRD-PARTY-LICENSES.md`, and every `.md` file under `docs/`. It removes code blocks, code spans, comments, link targets, and URLs. It then finds each all-caps token of two or more letters. Each token must have a glossary row or be in the `notAbbreviations` list of words that are not abbreviations. The test also fails if a word is in both places. Refs #452 `./scripts/gate.sh` passes on this commit. Closes #452

hexajon added 3 commits

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

docs: add a glossary of the abbreviations the docs use 8296464a79

docs/GLOSSARY.md gives the full form and a short meaning of each
abbreviation in the docs tree (WCAG 3.1.4, technique G62). The docs hub
and the root README link it. TestGlossary keeps the table in alphabetical
order with three filled cells per row and checks both links.

Refs #452

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

Add the 18 missing terms (PKCE, SQL, the license IDs, the signal names,
and others). Give OMP its full form, Oh My Pi. Say that the install
script, not madtea, runs GPG. Spell color as the rest of the docs do.

TestGlossaryCoversDocAbbreviations scans the doc prose for all-caps
tokens and fails on any token with no glossary row and no entry in
its list of words that are not abbreviations.

Refs #452

test: list REQUIRED as an emphasis word, not an abbreviation

drift / govulncheck (pull_request) Has been skipped

Details

drift / surface-diff (pull_request) Successful in 2m38s

Details

drift / forgejo-smoke (pull_request) Has been skipped

Details

ci / gate (pull_request) Failing after 21m46s

Details

drift / govulncheck (push) Has been skipped

Details

drift / surface-diff (push) Successful in -42s

Details

drift / forgejo-smoke (push) Has been skipped

Details

ci / gate (push) Failing after 21m25s

Details

eed44d2707

hexajon merged commit eed44d2707 into main

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

No reviewers

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

sixfold-space/madtea!861

No description provided.

Rows
Columns