Jargon Glossary¶
Document — instantiates Code / Register Adaptation
Defines specialized terms and acronyms so participants can cross a vocabulary boundary without losing precision.
A Jargon Glossary is a unidirectional reference: an alphabetized list that names the specialized terms and acronyms of one community and defines each one for people who don't yet have that code. Its defining move is keeping the specialist term while adding a doorway to it — it does not replace "idempotent" with a plain paraphrase, it defines "idempotent" so a newcomer can start using the precise word correctly. This is layering, not translation: the controlled vocabulary stays intact and precise; the glossary is the on-ramp beside it. It answers "what does this term mean?" for outsiders, not "what does your community call our concept?" between peers.
Example¶
A fast-growing open-source infrastructure project keeps losing first-time contributors in its issue tracker. Maintainers casually write "the reconciler is thrashing because the CR's finalizer blocks GC," and a capable newcomer who could fix the bug bounces off a wall of unexplained terms. Rather than rewrite every issue in plain English — which would strip the precise vocabulary the maintainers genuinely need — the project publishes a standardized glossary in its contributor docs. Each entry keeps the real term and adds a concise definition: Reconciler — the control loop that repeatedly drives actual state toward desired state. Finalizer — a marker that blocks deletion of a resource until cleanup runs. The glossary lives in the docs sidebar and is auto-linked wherever a term appears in the tracker, so the definition is one hover away at the point of confusion.
The result is not simpler issues but accessible precise ones: the newcomer learns to wield "finalizer" correctly instead of being handed a vague substitute, and the maintainers keep the exact language their work requires. The project models the entries on a public standardized glossary of the kind that mature technical communities maintain.[n1]
How it works¶
- Inventory the terms that actually block people. Harvest the acronyms and specialist words newcomers stumble on — from support questions, onboarding notes, and confused threads — rather than defining everything.
- Define, don't paraphrase-away. Each entry keeps the specialist term as the headword and gives a short, precise definition (plus an example where the concept needs one), so the controlled vocabulary survives.
- Fit the definition to its host genre. A tooltip gets one line; an onboarding handbook entry can carry an example and a "see also." The glossary's form is shaped by where it is consumed.
- Place it at the point of confusion. Embed or link it where the terms occur — a glossary nobody can find when stuck is dead weight.
Tuning parameters¶
- Inclusion threshold — define only true blockers vs. every specialized term. A lean glossary stays maintained and used; an exhaustive one becomes a second manual nobody reads and rots faster.
- Definition depth — a one-line gloss vs. definition-plus-example-plus-caveats. Depth aids genuine understanding but lengthens entries and slows upkeep.
- Embedding — standalone appendix vs. inline auto-linked terms vs. hover tooltips. Tighter embedding delivers the definition exactly when needed but costs tooling to maintain.
- Freshness cadence — how often the list is reconciled against current usage. Frequent review prevents stale or renamed terms from misleading; infrequent review lets the glossary drift out of sync with the community it serves.
When it helps, and when it misleads¶
Its strength is that it lets a community keep its precise vocabulary and stay open to newcomers — the specialist term and its doorway coexist, which is exactly the layering the archetype prefers over blunt substitution. It is the low-cost first move whenever the barrier is genuinely lexical: onboarding, cross-team documentation, standards references.
But a glossary is only a lexical on-ramp, and its classic misuse is being mistaken for the whole adaptation — the archetype is blunt that "a glossary alone is not Code / Register Adaptation." Defining every term does nothing about a tone that signals outsiders don't belong, an inaccessible genre, or a register that condescends; a message can be fully glossed and still alienating. The other failure is glossary rot: definitions drift from evolving usage, terms get renamed and the entry silently misleads, and an unmaintained list becomes worse than none. The guarding discipline is to scope the glossary honestly as one mechanism, pair it with register and exclusion work done elsewhere, and reconcile it against live usage on a set cadence.
How it implements the components¶
jargon_inventory— the glossary is this inventory made durable: the catalogued set of specialized terms and acronyms with their definitions.channel_and_genre_constraint— its form bends to its host (tooltip, sidebar, appendix, handbook entry), fitting the definition to the genre and channel where the term is met.
It does not map one community's words to another's or verify meaning survives a rewrite: bidirectional term-to-term mapping with match-type flags (translation_mapping, meaning_preservation_check) is Crosswalk Glossary's job — that twin translates between two peer codes, while this document defines one code for outsiders — and building role-specific versions of a message (source_message_or_meaning) belongs to Stakeholder-Specific Brief.
Related¶
- Instantiates: Code / Register Adaptation — supplies the vocabulary-boundary on-ramp that lets outsiders enter a specialist code without discarding it.
- Sibling mechanisms: Community Language Review · Crosswalk Glossary · Expert-to-Public Translation · Multilingual Switching Protocol · Plain-Language Translation · Register-Shift Guideline · Stakeholder-Specific Brief · Teach-Back Comprehension Check
Editorial Notes¶
Form Classification¶
Form family: Representation, Specification & Plan
Rationale: Jargon Glossary operates as a non-executable information artifact that externalizes static or prospective structure because it defines specialized terms and acronyms so participants can cross a vocabulary boundary without losing precision
Independent corroboration: The frozen evidence defines Jargon Glossary as 'Defines specialized terms and acronyms so participants can cross a vocabulary boundary without losing precision', so its operative form is Representation, Specification & Plan.
Review outcome: Independent reviewer agreement; high confidence.
Origin Attribution¶
Primary origin: Linguistics & Semiotics
Origin pattern: Cross-disciplinary synthesis
Present-day reach: Universal
Rationale: Lexicography and terminology studies formalized controlled definitions that preserve specialist terms while opening them to outsiders.
Related originating lineages:
- Library & Information Science — Reference and controlled-vocabulary practice materially shaped alphabetized, maintained glossaries.
Review resolution: Both independent reviews place the primary lineage in linguistics_semiotics. The queued differences (domain_reach_disagreement) concern secondary metadata rather than primary provenance. The final retains library_information_science only where a reviewer supplied a formative-lineage rationale; downstream application by itself is not treated as origin. origin_mode=cross_disciplinary_synthesis records the relationship among origin traditions, while domain_reach=universal records application breadth separately. encyclopedia_synthesis=false reflects whether either reviewer identified a corpus-specific synthesis, and confidence=high preserves the more cautious evidence assessment.
Review outcome: Reconciled after independent review; high confidence.
Notes¶
[n1] A controlled vocabulary is a curated, standardized set of terms with fixed definitions used to keep usage consistent; public examples include the standardized glossaries mature technical projects publish so newcomers learn the exact terms rather than vague substitutes. It is the model for keeping the specialist word intact while adding a definitional doorway. ↩