One glossary to rule them all: terminology management at scale
summary
Organization implements a machine readable single source glossary housed in a GitHub repo, authored as a YAML termbase and packaged as a Hugo module + YAML termbase that projects vendoring pulls with hugo mod get. Entries have short and long definitions, synonyms and product tags; CI scripts check ordering; a Hugo shortcode renders tooltips in support and API docs. New terms auto-push to Crowdin via its API for automatic Crowdin sync. System is live, collaborative and still evolving.
AI-written summary · about
chapters (20)
- 0:00Terminology management intro
- 1:08Scaling glossaries across platforms
- 3:35Terms that do exactly what they say
- 5:00Term bases and structure
- 6:47Cross-disciplinary working group
- 10:24Machine-readable single-source glossary
- 13:18YAML glossary structure
- 15:47Standardizing glossary processes
- 18:16Glossary tooltips in docs
- 22:28Integrating glossaries with translation
- 24:57Multilingual glossary
- 25:39Governance and collaborative maintenance
- 27:02Q&A: Term base vs glossary
- 28:25Q&A: Handling contentious terms
- 30:53Q&A: Enforcing term usage
- 32:37Q&A: Automating term detection
- 35:03Q&A: Terms with multiple definitions
- 36:28Q&A: Defining terms and competitor analysis
- 38:11Q&A: Preventing product acronyms
- 40:16Closing remarks
related talks
31mWhatchamacallit: Controlled Vocabularies for Technical Writers
13mDemystifying Cloud Native Concepts for the Business World
36mIf you build it, they will come: Our journey to unified (and discoverable) docs
42mEngineering Documentation
47mEngineering Documentation
45mUseful and Beautiful Developer Docs and How to Create Them
44mPushing documentation (so it doesn't hurt anymore)
01h 01mClosing the documentation gap with Backstage.io