Shareable glossaries
The shareable glossaries project is developing standards, tools and processes to help establish interoperable glossaries between organizations and projects.
Glossary inheriting terms.
About shareable glossaries
Glossaries are easy to set up for simple examples but very hard to scale - especially when you try to scale across use cases, across domains and across different organizations.
Unfortunately, in 2022, the world is yet to:
- Agree on a common glossary format.
- See the format widely adopted.
We aim to change this by breaking down technical barriers, raising awareness of solutions, and supporting widespread adoption of shareable glossaries.
Why are glossaries hard?
As projects and their teams grow, documentation becomes increasingly important to enable clear communication. At the same time, it becomes harder to maintain unambiguous terminology due to competing source material and team priorities.
While there are mature standards and supporting tools for publishing and maintaining controlled vocabularies, there is currently a high technical barrier to learning these - something we hope to help simplify.
More details in the modeling primer.
Use cases
Viral uptake of shareable glossaries depends upon the realization of two key use cases:
- Hover-over term popups in webpages, sourced from a glossary file.
- A tool which builds a glossary f technical terms in my website, as sourced from authoritative glossaries.
Refer to glossary use cases for more use cases and more details.
Maturity levels
A glossary should start small, with minimal metadata fields. As the glossary matures, more metadata fields can be added to address advanced use cases.
| Level | Value added |
|---|---|
| 0 No glossary | |
| 1 Non-shareable | Help a reader understand locally defined terms. |
| 2 Machine readable | Enables tooling, like domain specific hover-over popups. |
| 3 Traced to source | Know which glossaries terms come from. |
| 4 Governed | Manage glossary maintenance. |
| 5 Extra metadata | Support power use cases. |
More details at shareable glossary maturity levels.
Roadmap to shareable glossaries
Some may think it optimistic to nudge the world toward adopting shareable glossaries. We believe it is achievable, within a few years, by: breaking the problem into solvable components, and collaborating with domain experts for each part of the problem.
These components include:
- Establish a development community.
- Establish a shareable glossary standard format.
- Publish prominent glossaries as a web service using this standard.
- Scale, by making it super-easy for projects to auto-generate a glossary file for their websites from authoritative glossaries.
- Incrementally add tooling to realize glossary use cases.
- Introduce governance best practices.
- Provide user, and implementation guides.
Refer to our detailed roadmap and current status for more details.