Terminology Engine v2 specifications

Introduction

Terminology Engine v1 (TEv1) is now operational; it enables us to not only define terminology, but also to actually put it to use and help readers of documentation understand what they read, and drill down to level of understanding that they seek (some are satisfied with the popups that appear on defined terms, others will click on the term to get further context and backgrounds). That is: after the existing documentation has been updated to take the full advantage of this tool.

Two of the major objectives of the eSSIF-Lab project include (a) the creation of an ecosystem of developers (and users) that continues to thrive after the project has died, and (b) ensure interoperability, which is not just about the technology, but about the documentation as well.

Given that different parties (subgrantees) will have use different vocabularies/terminologies, we seek for ways to ensure terminological interop while accommodating each party's specific terms.

Purpose

The main objective of TEv2 would then be to facilitate the new version of the eSSIF-Lab architecture, that is going to be constructed by eSSIF-Lab consortium partner(s), every subgrantee of the infrastructure call, and each subgrantee of BOC#1 that produces (open source) components that extend the infrastructure. The resulting architecture should contain a functional description of each of these components, and this description must be embedded in the 'integral whole'.

High-level requirements

The high-level requirements of TEv2 are:

• Writing terminology and other documentation shall be easy for different authors. This means that they must not be required to go through an extensive learning-cycle. Also, they should be provided tooling that helps them to write documentation that passes the CI-pipe without any problems, specifically by not only pointing out whether or not they made a mistake, but as much as possible by identifying where, in their own documents, the cause of the error lies, and what it takes to fix it.

• It should be possible for authors to keep their documentation (including term-definitions) separate from that of other subgrantees (in a 'scope' of their own), so that they can document their stuff in an internally consistent/coherent way without being bothered by terms that others use. This scope may also serve as a namespace. Ideally, they should be able to write their documentation irrespective of the implementation of the TEv2 (meaning that it would work equally well if TEv2 were implemented as a Docusaurus extension or as a stand-alone tool (that e.g. could update a Confluence or wiki site).

• It shall be possible to work with multiple such scopes (see the terminology-pattern when that becomes available). A scope has its own vocabulary, which consists of the terms (and other stuff) defined within that scope, supplemented with terms that are defined in other scopes/namespaces (where the term itself may be changed if that is appropriate for that scope).

• It shall be possible for authors to use terms in their documentation files that have been defined within the scope in which that file is created, where 'using a term' means that it is made to stand out when rendering the document, that it has a popup, and that clicking on it navigates the user to the place where it is defined (as in TEv1). It shall also be possible to use terms that are defined in another scope, provided that the scope supports TEv2 functionality.

• For existing terminologies, such as that of NIST, DIF, Sovrin, etc., that do not support TEv2 functionality, we may decide to create a scope within the eSSIF-Lab context that does support TEv2 functionality, thus allowing authors to refer to such terms with all the benefits that TEv2 brings.

• It shall be possible (for technically sufficiently capable engineers), to create generators that take one or more source file(s) from documentation authors, and create artifacts from that, e.g. for making dictionaries, concept-graphs, statistics and more. Note that this item only requires that such engineers be facilitated to create such generators. Nevertheless, for maintainability, it is suggested that every scope should contain a directory generator-specs, that contain the files that generators use to generate their artifacts. Such specification files would conform to the generic TEv2-document-template described above, where their type-attribute would correspond with the generator. So a file that would specify an artifact to be generated by e.g. the xxx-generator would specify xxx in its type field (so glossary and dictionary would be valid xxxs, but we can think of (but not necessarily implement more).