Skip to content

Glossary Governance

A glossary is the most-consulted, most-neglected document in most projects. This page describes FCC's approach to glossary as a governed, cross-referenced, multi-audience asset, and how to adopt it.

Why glossaries decay

Typical failure modes:

  • Accretion without pruning. Terms added; terms never retired.
  • Multiple glossaries. One per audience, inconsistent definitions.
  • Orphan terms. Defined in the glossary, never referenced in the body.
  • Ghost terms. Used in the body, never defined.
  • Out-of-date. The product changes; the glossary doesn't.

FCC mitigates each with a specific discipline.

Single source of truth

One YAML file, many output pages:

- id: riscear
  short: "Role, Input, Style, Constraints, Expected Output, Archetype, Responsibilities, Role Skills, Role Collaborators, Role Adoption Checklist."
  long: >
    The ten-component persona specification that defines every FCC role.
    Authored in a YAML file per persona; validated by a JSON schema.
  audiences: [all]
  first_introduced: v1.0.0
  related: [persona, model-card]

- id: persona
  short: "A YAML document defining one role in an FCC system, carrying ten R.I.S.C.E.A.R. fields and metadata."
  long: >
    Personas are the unit of authorship in FCC. Each persona has an id,
    category, risk classification, and a complete R.I.S.C.E.A.R. spec.
    FCC ships 164 personas across 20+ categories plus six vertical packs.
  audiences: [all]
  first_introduced: v1.0.0
  related: [riscear, model-card, archetype]

Render this to different pages per audience (the policy glossary, the engineer glossary, the beginner glossary) using the same template pipeline you built for persona-driven docs.

Audience tagging

Each term is tagged with audiences it is relevant to:

  • all — everybody needs this term.
  • policy-makers — regulatory / governance flavor.
  • engineers — implementation-specific.
  • students — pedagogical simplification.
  • journalists — public-facing precision.

A template filter emits only terms relevant to the current glossary. A policy-makers glossary drops importlib.resources; an engineers glossary drops the detailed regulatory citations.

Same source; different renderings.

Short vs. long definitions

Every term has:

  • short: one sentence, the TL;DR.
  • long: two-to-five sentences, with caveats and context.

Render short in tooltips, sidebars, "See also" sections; render long in the main glossary entry. Readers get the right density for the context.

Cross-referencing

The related field names other terms. The template:

  • Hyperlinks related entries from each term's page.
  • Builds an alphabetical index at the top.
  • Builds a graph of inter-term references at the bottom (optional but popular).

This makes the glossary navigable. A reader landing on riscear can hop to persona and then to archetype without searching.

Versioning

The first_introduced field records which release introduced the term. Two benefits:

  • Readers of older versions see only terms valid at their version.
  • Deprecations can be tagged with deprecated_in: v1.9.0 and surfaced prominently.

FCC's glossary carries both fields. It prevents the "wait, when did that word start being used?" question.

Orphan and ghost detection

Two lints close the most common quality gaps:

  • Orphan lint. For each term in the glossary, grep the docs; if no match outside the glossary itself, warn. The term is defined but unused.
  • Ghost lint. Maintain a list of capitalized or jargon-ish words; for each, check the glossary. Warn on unknown words. Humans review weekly.

Both lints run in CI. Neither blocks PRs; both are advisory signals.

Multi-word terms

Glossaries often miss multi-word terms ("evidence graph," "R.I.S.C.E.A.R. checklist"). Two practices help:

  • Use id for the slug, title for display. E.g., id: evidence-graph, title: Evidence Graph. Template links use the id; prose uses the title.
  • Permit alternates. An aliases field catches "risk heat-map" alongside risk heatmap.

Consistency with code

Terms that map to code concepts should reference the code:

- id: model-card
  short: "A Markdown document per persona, modeled on Mitchell et al. 2019."
  code_ref: "src/fcc/evaluation/cards.py::ModelCard"

CI checks that the code_ref resolves. If the class is renamed, the build fails, prompting a glossary update.

Multi-language readiness

FCC's v1.6 shipped seed translations (FR, ES, DE). The glossary was designed for this from the start:

  • Strings are in a locales/ tree keyed by language code.
  • The template picks the locale at render time.
  • Untranslated terms fall back to the source language with a visible "Untranslated" tag.

If internationalization is plausible for your project, design the schema for it now. Retrofitting is painful.

Governance rhythm

A glossary review cadence prevents silent decay:

  • Weekly. Triage new terms suggested by contributors. Accept, reject, or request more detail.
  • Monthly. Run the orphan and ghost lints; act on warnings.
  • Quarterly. Full sweep: verify first_introduced, check for deprecation candidates, refresh related links.
  • On release. Update first_introduced for any new term introduced this release.

This takes under 2 hours per month and pays back in docs trust.

The "don't define X without Y" rule

A term that references another term in its definition must list that term in related. A term that doesn't follow this rule is failing its job; the reader needs to know what prerequisites they need.

CI lint: for each term's long text, tokenize; cross-reference against related. Warn on unlinked term-word use.

Multi-audience glossary patterns

Three patterns in practice:

  • Single merged glossary — all terms, audience tags, one alphabetical list. Simple; can be overwhelming.
  • Per-audience glossaries — one page per audience with only relevant terms. Cleaner for each reader; requires discipline to keep definitions consistent.
  • Primary glossary + jump pages — one canonical glossary; audience-specific landing pages link into the primary. FCC uses this pattern.

Pick based on your audience size and overlap.

Adoption path

A minimum viable adoption:

  1. Day 1. Create a glossary.yaml with your ten or twenty most important terms.
  2. Day 2. Write a template that renders it to one glossary.md.
  3. Week 1. Add front matter and audience tags to terms.
  4. Week 2. Add short/long split; link related.
  5. Month 1. Introduce orphan and ghost lints.
  6. Month 2. Internationalize if relevant.

Start; iterate; never scrap and restart.

Small writerly details

  • Sentence case for titles. "Evidence graph," not "Evidence Graph," except when "Evidence Graph" is the code class name.
  • No "etc." in definitions. Exhaustive or representative-and-label-it.
  • No circular definitions. If term A's definition mentions term B, term B's definition must not mention term A in its short.
  • Prefer active voice. "A persona defines..." beats "A persona is defined as..."
  • Write for the reader at their worst moment. They are reading your glossary because they are confused. Be generous.

Where next

With glossary governance in hand, return to the generated-docs pattern in Persona-Driven Docs, or to the pipeline-wide view in Publication Pipeline 101. For sources and tools, Further Reading.