Make Terms Clear, Consistent, and Linkable
Glossary & Definitions Governance
A shared glossary reduces confusion, speeds onboarding, and helps search engines and AI understand your content. This standard covers entity inventory, naming rules, disambiguation, anchors, cross-links, and schema. It follows Google guidance on helpful content and crawlable links, plus NN/g research on descriptive link text.
Objective and scope
Standardize how your team defines and links the terms that appear across docs, blog posts, solution pages, and product UI. The glossary should be easy to skim, easy to link, and simple to maintain.
Entity inventory
Start with a list of terms that readers must understand to use your product or evaluate a purchase.
- Core concepts: the category, key metrics, roles, common tasks
- Product entities: features, objects, integrations
- Industry terms: standards, protocols, regulations
Collect terms from support tickets, sales calls, and docs. Prioritize by frequency and confusion risk.
Naming conventions
Primary name
- Use the term most readers expect
- Capitalize proper nouns consistently
- Avoid trademark symbols in headings
Variants
- Record common spellings and abbreviations
- Choose a canonical slug that matches the primary name
- Redirect variants to the canonical page
Formatting
- Hyphenate compound modifiers when needed for clarity
- Use sentence case for definitions and examples
- Keep titles short and scannable
Disambiguation and synonyms
Some terms mean different things in different contexts. Handle that up front.
- Add a one-line “In analytics, X means … In security, X means …”
- List synonyms and near-synonyms, then point to the preferred term
- If two terms are truly different, create separate entries and cross-link
Entry structure and style
Required fields
- Definition in 1 to 3 sentences
- Why it matters, in plain language
- Example or short formula if relevant
- Related terms with links
Clarity first
- Use everyday words, avoid unexplained jargon
- Prefer active voice and short sentences
- Define acronyms the first time
PlainLanguage.gov has practical rules for clear writing. See the guidelines.
Evidence
- Link to standards or docs near claims
- Date any volatile facts
- Use descriptive link text, not “click here”
NN/g on link text shows why anchors should describe the destination.
Example entry layout
| Field | Content |
|---|---|
| Term | Activation rate |
| Definition | The share of new accounts that complete a defined first-value event within a set time window. |
| Why it matters | Correlates with retention and revenue. Teams use it to compare onboarding flows. |
| Example | Activation rate = activated accounts ÷ new accounts, window 14 days. |
| Related | Retention rate, Time to value |
Anchors and cross-linking
Make every term linkable and easy to reference inside content.
- Each entry gets a stable URL and an on-page anchor
- Use descriptive anchors in articles, not generic text
- Add a “Related terms” block to encourage deeper reading
Use real <a href> links. Google explains crawlable link requirements in Search Central.
Folders, slugs, and taxonomy
URL pattern
- Use a single folder like /glossary/
- Slugs match the primary term, lowercase and hyphenated
- Redirect legacy paths and variants to the canonical entry
Navigation
- Alphabetical index with jump links
- Search field that filters by title and definition
- Breadcrumbs back to the glossary hub
Clusters
- Tag entries by theme, role, or product area
- List clusters on the hub for exploration
- Link cluster pages from relevant guides
Schema: DefinedTerm and sets
Use JSON-LD so each entry is a clear entity. Mark the hub as a DefinedTermSet, and each entry as a DefinedTerm. Keep markup in parity with the visible page. Google’s structured data intro is here: Structured data.
Hub example
<script type="application/ld+json">
{
"@context":"https://schema.org",
"@type":"DefinedTermSet",
"@id":"https://accordcontent.com/glossary/#set",
"name":"Accord Content Glossary",
"url":"https://accordcontent.com/glossary/"
}
</script>Entry example
<script type="application/ld+json">
{
"@context":"https://schema.org",
"@type":"DefinedTerm",
"@id":"https://accordcontent.com/glossary/activation-rate/#term",
"name":"Activation rate",
"url":"https://accordcontent.com/glossary/activation-rate/",
"inDefinedTermSet":{"@id":"https://accordcontent.com/glossary/#set"},
"description":"The share of new accounts that complete a defined first-value event within a set time window."
}
</script>Measurement and maintenance
Search Console
- Track clicks and CTR to the /glossary/ folder
- Watch query mix for definitions and “what is” terms
- Compare before and after internal linking changes
GA4 engagement
- Event for glossary link clicks inside articles
- Session share that includes at least one glossary view
- Read-next CTR from entries to related guides
GA4 docs: events and conversions.
Refresh cadence
- Quarterly check for new terms and duplicates
- Annual review of high-traffic entries
- Change log with dateModified on the page
Templates and checklists
Entry template
Term: ______________________
Definition (1–3 sentences):
Why it matters:
Example or formula:
Related terms (links):
Primary source or standard:
Owner:
dateModified:QA checklist
- Definition is clear, jargon is explained
- Primary name and slug match, variants redirect
- Anchors and related links present and crawlable
- Schema validates and matches the visible entry
- Entry is linked from at least one hub or guide
- Accessibility basics: headings, alt text, focus states
FAQ
Should every term get its own page
No. Start with terms that unlock understanding or appear across multiple pages. Group minor terms on a single page until demand grows.
How long should definitions be
Short enough to scan, long enough to remove ambiguity. Most are 50 to 120 words plus one example.
Do glossary pages help SEO
Yes when they clarify concepts and connect readers to deeper content. Keep links crawlable and anchors descriptive per Google and NN/g guidance.
Can we include equations and images
Yes. Add alt text and captions. Keep examples simple and reference the source when you cite standards or formulas.