Cross-domain management of glossaries

Image by Chris Dlugosz

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 organisations.

We are kicking off a pilot project to address cross-domain management of glossaries and preferred word lists. The pilot will build processes and tools for the generic use case, developing and applying them within the geospatial mapping domain.

Communication about this document will be on the OSGeo Lexicon email list. (Check your spam for confirmation email after subscribing.)

Goals

We aim to achieve the following:

• Create best practices in cross-domain glossary management, for adoption by the technical writing community.
• Build a community who define and manage geospatial terms across multiple geospatial communities.

Use cases

This project is designed to address the following use cases:

1. As a general document reader, I want to find definitions for the terms and acronyms in the document I am reading. There may be multiple definitions for a term, determined by context, or having multiple upstream source definitions.
• Ideally identified terms can be highlighted, and readers can hover over terms to get a popup with more information.
2. As an advanced document reader or term maintainer I want to understand the inheritance path back to upstream source definitions.
3. As a technical writer, I want to find the preferred spelling, capitalization and word choice for a term.
4. As a technical writer, I want a tool which builds a glossary of the organisation specific terms used within my document, by searching my organisation’s glossary.
• As a minimum, this will search a document for acronyms, and match against provided glossaries.
• Missing or duplicate terms will be flagged.
• Existing terms will be highlighted according to [preferred, alternative, deprecated] status.
5. As an organisation, I’d like a tool which seeds my organisation specific glossary by searching my organisation’s docs for terms in a superset of reference glossaries.
6. As a document translator, I want glossary terms to be translated into my target languages, so I can consistently translate a source term to the same target term.
7. As a project, I want a glossary which includes terms specific to my project, as well as terms sourced from multiple external glossaries.
8. As a foundation, I want a glossary which sources terms from my many sub-communities.
9. As a glossary owner, I want to ensure my glossary is continuously updated to align with updates in my source glossaries.
10. As a glossary owner, I want a governance framework to help resolve terminology management conflicts between terminology sources and stakeholders.
11. As a software developer, I want terms and relationships between glossaries in a machine-readable form so that I can integrate glossary functionality into software.
12. As a data modeller, I want the terms described in my model to use existing term definitions, (from APIs, standards, etc), as defined within my domain, so that I can share my terms with others, and seamlessly integrate datasets from multiple sources.
13. As an application using a glossary, I want terms defined with a consistent schema which facilitates machine readability and interoperability
14. As a researcher, I want to be able to find related information even if it uses different terms for the same concepts.
15. As a content manager, I want to apply a preferred term as metadata to enable retrieval of digital content across disparate source repositories.
16. As a search engine or software algorithm building knowledge graphs, I want to use glossaries to help extract meaning from textual information sources.

Scope

The pilot project will focus on the geospatial domain, which has an advanced ecosystem of stakeholders and technologies. However, the templates and processes will be developed to be broadly applicable for all software ecosystems managing glossaries.

Schedule

• August 2020: Kickoff
• December 2020: Soft launch at the Write the Docs Australia/India conference
• February 2021: Hard launch

This schedule aligns with The Good Docs Project's Season of Docs initiatives.

Deliverables

The following deliverables are likely to be achieved within the pilot’s timeframe:

Schemas

1. Schema for a preferred word list. For example: Word list | Google developer documentation style guide.
2. Schema for a term definition. For example: ISO/IEC Directives art 2, Principles and rules for the structure and drafting of ISO/IEC documents - 16.5.5 Term and 16.5.6 Definitions.
3. Schema for translation of terms between languages

Processes

1. Process for a central glossary owner to accept, triage, and refine proposals for new terms from their community:
• As single terms.
• As a curated set such as a word-list from an authoritative source.
2. Process for deciding the point of truth for a term within a glossary, be that from a central glossary or from a leaf glossary.
3. Process for handling multiple definitions of a term, which may differ across contexts.
4. Process for notifying updates to a glossary.
5. Process for managing the lifecycle of terms.
6. Version management of individual terms.
7. Version management of schemas.
8. Version management of a glossary as a whole.
9. Version management of processes.
10. Version management of tooling.

Guides

1. How-to guide for a project to set up their own glossary by selecting a subset of master glossaries plus adding their own terms.
2. How-to guide for setting up a master glossary.
3. How to handle aggregation and overlaps between sets of terms and mappings between similar terms used in different contexts.

Tools

1. Tool for managing glossary terms through a standards based lifecycle such as OGC’s statuses:
• Submitted
• Accepted
• Experimental
• Valid
• Superseded
• Deprecated
• ...
2. Tools for publishing a glossary in human readable form,
3. Including key relationship visualisation and navigation support.
4. Tool for publishing a glossary in machine readable form,
5. Facilitating features such as mouse-over popups.
6. Tools for exporting from a master glossary into other publishing mediums, such as a page within another website or Content Management System (CMS).

Geospatial domain deliverables

1. Term management committees:
• OSGeo Lexicon committee managing OSGeo terms.
• OGC Naming Authority committee managing policies and final publication for OGC geospatial standards terms.
• ISO TC211 committee managing ISO geospatial standard terms.
• [Optional] Specific software project committees managing their project’s terms.
2. Definitions for OSGeo terms
3. Translations of OSGeo terms
4. Glossary Web Services:
• OSGeo Foundation Glossary Web Service.
• OGC Glossary Web Service.
• ISO TC211 Glossary Web Service.
• [Optional] Multiple OSGeo projects standing up their own glossary instance. For instance, set up one for QGIS and/or PostGIS.
5. Publishing glossaries:
• Publishing of Glossary within Geoforall Newsletter
• Publishing of Glossary within OSGeoLive documentation

Why now? Why Geospatial?

As of August 2020, many things are lining up to enable us to collectively solve the tough challenges around the cross-domain management of glossaries.
Aligning activities include:

1. The Good Docs Project has been making progress tackling technical writing problems. We have recently built a How to apply/customise a writing style guide for software projects. A next step is to explain how to apply word lists and glossaries. And we have volunteers willing to push this forward.
2. The geospatial community is very advanced at trying to solve terminology management challenges:
• Through the OSGeo Foundation, we have relationships with ~ 50 geospatial open source projects who all need glossaries, and through the OSGeoLive project we have contact points with each of these projects as well as access to volunteer translators for OSGeo documentation. In the 2019 Season of Docs program we connected with all these communities and updated their quickstarts. We can do it again for glossaries.
• We have experienced volunteers from the OGC and ISO TC211 standards bodies keen to bring their expertise to advance this challenge. These volunteers are already working on this problem.
• From the ISO TC211 and OGC communities, we have access to open source software for term management and access to the people who wrote it.
• Through the Geolexicon working group, we have OSGeo volunteers who have been maintaining a glossary of terms. They will be able to apply these terms and add more.
3. The Good Docs Project is starting a sprint of work, aligned with Google's Season of Docs. We are shooting for a soft launch in December 2020, hard launch around February 2021. This helps frame a sense of purpose, timing, and scope which we can tap into.
4. There are other initiatives within The Good Docs Project which will complement this work and facilitate cross-pollination of ideas.
5. ISO/TC 211/TMG is redeveloping its Multi-Lingual Glossary of Terms (MLGT) as an ISO SMART project for machine-readable/interpretable terminology that encompasses management of life- cycle to the usage of such content.
6. The ISO/TC 211 MLGT SMART work is performed in partnership with Ribose who supplies the Glossarist software and the Geolexica terminology web platform. Ribose volunteers to support OSGeo lexicon work and its workflow in both of these offerings.

Postnote

A variant of this blog was picked up by the OGC.