§ Terminology Governance Guide

Specification Status: v0.6 Draft

Latest Draft:

https://github.com/henkvancann/terminology-governance-guide

Editors:

• Henk van Cann, Blockchainbird.org

Contributors:

• Neil Thomson
• Darrell O’Donnell, Continuum Loop Inc.
• Rieks Joosten
• Drummond Reed
• Ed Eykholt
• Kor Dwarshuis
• Kevin Griffin, GLEIF
• Daniel Hardman, Provenant, Inc

Participate:

In the Guide:

| TBW |

Template improvements:

GitHub repo

Commit history

§ Status of This Memo

The document structure is based on a template specification for ToIP.

This document is a guide for spec authors and a discription of how the tooling works. The normative section is aimed at developers of the specification template mentioned above.

§ Copyright Notice

This specification is subject to the OWF Contributor License Agreement 1.0 - Copyright available at https://www.openwebfoundation.org/the-agreements/the-owf-1-0-agreements-granted-claims/owf-contributor-license-agreement-1-0-copyright.

If source code is included in the specification, that code is subject to the Apache 2.0 license unless otherwise marked. In the case of any conflict or confusion within this specification between the OWF Contributor License and the designated source code license, the terms of the OWF Contributor License shall apply.

These terms are inherited from the Concepts and Terminology Working Group at the Trust over IP Foundation. Working Group Home

§ Terms of Use

These materials are made available under and are subject to the OWF CLA 1.0 - Copyright & Patent license. Any source code is made available under the Apache 2.0 license.

THESE MATERIALS ARE PROVIDED “AS IS.” The Trust Over IP Foundation, established as the Joint Development Foundation Projects, LLC, Trust Over IP Foundation Series (“ToIP”), and its members and contributors (each of ToIP, its members and contributors, a “ToIP Party”) expressly disclaim any warranties (express, implied, or otherwise), including implied warranties of merchantability, non-infringement, fitness for a particular purpose, or title, related to the materials. The entire risk as to implementing or otherwise using the materials is assumed by the implementer and user. IN NO EVENT WILL ANY ToIP PARTY BE LIABLE TO ANY OTHER PARTY FOR LOST PROFITS OR ANY FORM OF INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES OF ANY CHARACTER FROM ANY CAUSES OF ACTION OF ANY KIND WITH RESPECT TO THESE MATERIALS, ANY DELIVERABLE OR THE ToIP GOVERNING AGREEMENT, WHETHER BASED ON BREACH OF CONTRACT, TORT (INCLUDING NEGLIGENCE), OR OTHERWISE, AND WHETHER OR NOT THE OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

§ RFC 2119

The Internet Engineering Task Force (IETF) is a large open international community of network designers, operators, vendors, and researchers concerned with the evolution of the Internet architecture and to ensure maximal efficiency in operation. IETF has been operating since the advent of the Internet using a Request for Comments (RFC) to convey “current best practice” to those organizations seeking its guidance for conformance purposes.

The IETF uses RFC 2119 to define keywords for use in RFC documents; these keywords are used to signify applicability requirements. ToIP has adapted the IETF RFC 2119 for use in the Terminology Specification Guide, and therefore its applicable use in ToIP-compliant governance frameworks.

The RFC 2119 keyword definitions and interpretation have been adopted. Those users who follow these guidelines SHOULD incorporate the following phrase near the beginning of their document: The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.

RFC 2119 defines these keywords as follows:

• MUST: This word, or the terms “REQUIRED” or “SHALL”, mean that the definition is an absolute requirement of the specification.
• MUST NOT: This phrase, or the phrase “SHALL NOT”, means that the definition is an absolute prohibition of the specification.
• SHOULD: This word, or the adjective “RECOMMENDED”, means that there MAY exist valid reasons in particular circumstances to ignore a particular item, but the full implications MUST be understood and carefully weighed before choosing a different course.
• SHOULD NOT: This phrase, or the phrase “NOT RECOMMENDED” means that there MAY exist valid reasons in particular circumstances when the particular behavior is acceptable or even useful, but the full implications SHOULD be understood, and the case carefully weighed before implementing any behavior described with this label.
• MAY: This word, or the adjective “OPTIONAL”, means that an item is truly optional. One vendor MAY choose to include the item because a particular marketplace requires it or because the vendor feels that it enhances the product while another vendor MAY omit the same item.

Requirements include any combination of Machine-Testable Requirements and Human-Auditable Requirements. Unless otherwise stated, all Requirements MUST be expressed as defined in RFC 2119.

• Mandatories are Requirements that use a MUST, MUST NOT, SHALL, SHALL NOT or REQUIRED keyword.
• Recommendations are Requirements that use a SHOULD, SHOULD NOT, or RECOMMENDED keyword.
• Options are Requirements that use a MAY or OPTIONAL keyword.

An implementation which does not include a particular option MUST be prepared to interoperate with other implementations which include the option, recognizing the potential for reduced functionality. As well, implementations which include a particular option MUST be prepared to interoperate with implementations which do not include the option and the subsequent lack of function the feature provides.

§ Foreword

This publicly available specification was approved by the ToIP Foundation Steering Committee on [dd month yyyy must match date in subtitle above]. The ToIP permalink for this document is:

[permalink for this deliverable: see instructions on this wiki page]

The mission of the Trust over IP (ToIP) Foundation is to define a complete architecture for Internet-scale digital trust that combines cryptographic assurance at the machine layer with human accountability at the business, legal, and social layers. Founded in May 2020 as a non-profit hosted by the Linux Foundation, the ToIP Foundation has over 400 organizational and 100 individual members from around the world.

Any trade name used in this document is information given for the convenience of users and does not constitute an endorsement.

This document was prepared by the ToIP Technical Stack Working Group.

Any feedback or questions on this document should be directed to https://github.com/trustoverip/specification/issues

THESE MATERIALS ARE PROVIDED “AS IS.” The Trust Over IP Foundation, established as the Joint Development Foundation Projects, LLC, Trust Over IP Foundation Series (“ToIP”), and its members and contributors (each of ToIP, its members and contributors, a “ToIP Party”) expressly disclaim any warranties (express, implied, or otherwise), including implied warranties of merchantability, non-infringement, fitness for a particular purpose, or title, related to the materials. The entire risk as to implementing or otherwise using the materials is assumed by the implementer and user. IN NO EVENT WILL ANY ToIP PARTY BE LIABLE TO ANY OTHER PARTY FOR LOST PROFITS OR ANY FORM OF INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES OF ANY CHARACTER FROM ANY CAUSES OF ACTION OF ANY KIND WITH RESPECT TO THESE MATERIALS, ANY DELIVERABLE OR THE ToIP GOVERNING AGREEMENT, WHETHER BASED ON BREACH OF CONTRACT, TORT (INCLUDING NEGLIGENCE), OR OTHERWISE, AND WHETHER OR NOT THE OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

§ Executive Summary

Governance and technical solution of our concepts & terminology for groups/scopes within ToIP and ToIP as a whole.

§ Conclusion

| TBW |

§ Introduction

In 2021 TrustoverIP published the Specification for Creating and Using Terms

In the years to follow the guide to create Term wikis has been established. It gives extensive instructions on how to create wikis, use markdown and hyperlinks, etc.

As the number of implementations grew, maintenance of the wikis became out of sync, the number of broken links increased, duplicate definitions of terms and deviations from the structure and governance offered.

Darrell O’donnell: As I am deep in a rabbit hole looking at definitions a thought occured to me. We may end up with “over-defined” terms - meaning the definition exists in multiple places. Have you considered that case? I believe that a ToIP Master : ToIP Specification conflict should be avoided. If a spec needs a different term than is in the Master glossary, then the conflict should be resolved: adjust Master Glossary; or create new term in Spec BUT where we end up looking at terms that are managed even further afield, this gets really hard. Just curious if this is a condition you’ve thought of. I see the following possibilities:

• multiple def: in single document (this is just sloppy work - but easy to do, for me at least)
• duplicated def: - say in Spec and ToIP Master Glossary

Some of these developments are part of the natural evolution of concepts and terminologies within an umbrella organisation like ToIP. Others could be more streamlined.

This specification intends to offer a Guide. A Guide has little or no normative statements as it describes an advise on how to create a specific terminology by sticking to guidance and certain rules to know how to write or adopt definitions, how to reference them and where to store and manage them:

• reuse the specification template and how to do this in a sustainable manner
• reuse the ToIP over-arching glossary where possible
• avoid breaking links in the future
• use the full power of def, refs and aliases in individual documents based on Spec-Up (which is behind specification template as of 202?)
• be able to generate your documents in a few leading style-guides like ToIP, ISO, etc.
• Last but not least: any group with a certain scope will need to source manage their own definitions or views on definition, which means that we need to ear mark creation and updates with time & author.

§ Historical perspective

§ Past Practise Terminology Governance

§ Current Practise Terminology Governance

§ Future Practise Terminology Governance

§ Scope

This Guide goes with the flow as much as it can. This means:

• git and github for version control, issue-handling and project management in the own github repo
• The existing Slack group CTWG for discussions
• Use of github wiki-based source management of terminologies
• Proposal to archive obsolete sources of terminology
• Reuse harvesting / consensus creation tools that are available and anticipate improvements of those
• Connect to TEv2 step by step
• Use Spec-Up / specification template and anticipate improvements of this

§ Roadmap

Let’s clear up the issues around TEv2 versus Spec-Up and KERISSE tooling. The goal is unification and we prevent reinventing tools that are already in place.

The issue of unification is open, and it might be solved. By whom is not yet clear. A sequence numbered roadmap to unification (presumming that that’s the goal) can be found below.

§ Temporary solution: pictures

§ How to write definitions in your terminology

1. Repeat the objectives or goals of a certain community
2. Discuss, communicate towards consensus about a certain concept or term
3. Define the scope or mental model together
4. Write criteria for which is inside or outside the reach of a certain term

Needless to say, this process is important for mutual understanding.

§ How to write criteria

1. Criteria must make sense for all roles involved in the community

For example a criterium like “A self-adressing identifier is automatically a self-sovereign identifier, but not the other way around.” might not resonate with a Reader.

2. Criteria should be deterministic, either to be in or out the definition

abbrev

a shorthand in capitals for a term. It may contain special characters. It may not contain spaces.
Criterium for not being an abbreviation: If the word is not in uppercase, in our context the word is more likely to be an alias for the term.

3. Formulate edge cases: What is just included a defnition, and what is just excluded from a definition?!

E.g. X.509 could be an abbreviation, and ‘EU ID’ is not an abbreviation

Some good news is that enhancement in the written version of concepts and terminology can be achieved in parallel with other activities:

• archiving old concept and glossaries
• tool development
• consensus building But unfortunately not together with referencing existing poorly-formulated definitions because that’ll put a burden on the future.

§ Towards automatic processing in github actions

Currently github wikis serve as the source management tool of the glossary terms in ToIP context. There are temporary exceptions.

Here are a few practical rules from the originator ToIP to get these wiki terms through their equivalent github actions script, please:

1. beware all new wiki items you create, lead to new .md files. We’d like to know
2. introduce lowercase names with spaces (they will convert into lower case names with dashes between the words)
3. start with ## Definition header; example
4. start with uppercase abbreviations with only the “## See” header; example
5. don’t delete items (i.e. .md files) but make clear they are depreciated and / or link to the new concept / term
6. don’t change or update the name of an item single handed, for it might change the concept / meaning for other people and create dead links for those who read - or link to the term. Please open an issue or a PR to discuss first.
7. any other immediate updates and amendments welcome, the revisions are available for us to be able to (partially) revert if something unwanted or unexpected happens.

Have fun CRU-ing!
'* CRU=Create Read Update

§ A glossary “reads” this wiki

Where as the wiki source management tool (or input tool) of terminology, there is no way to add metadata to the terminology.

Currently some ToIP groups use workarounds to add metadata and extra functionality to their wiki terminology, based on the combination of labelling content and extra metadata. E.g. The WebofTrust-harboured engine KERISSE regularly scrapes the the WOT-terms wiki into KERISSE, we add features and metadata through a Google Sheet, we connect relevant matching terms from related glossaries and finally we index it for the KERI Suite Search Engine (KERISSE).

| TBW |

§ Roles

This section is informative.

A clear specification of roles in- and outside an average ToIP “group” might clear up the different viewpoints people have when looking at concepts and terminology.

1. minimalistic use cases for them
2. then the necessary consecutive steps to get there

§ Role: ToIP glossary maintainer

Uses: Source management tool. Reads and compares concepts in text and terminology in glossaries, (for example generated by Spec-Up) to use within his/hers “own” over-arching ToIP glossary. He/she builds as muchn consensus around terms and concepts and promotes using the ToIP glossary as reference material.

§ Role: Specification author

Uses: an IDE, git and a browser extension, to edit Spec-Up markdown files for his/her specific context (mental model) in a version managed environment, authenticated, to write the concept and specification and offer this as a PR. He/she uses browser extensions to check technical consistency of the links in the text and harvest a personal collection of term definitions.

§ Role: Curator

Uses an IDE and git and browser extensions, to check logical consistency & meaning of term definition in a certain context and uses browser extensions to harvest a personal collection of term definitions, based on those recommended by the specification authors.

§ Role: Reader

Uses github.io website, reads concepts in text and terminology in glossaries, (for example generated by Spec-Up) with its own tailor-made contextual glossary that generates pop-ups here and there in the text offered.

§ Process and roles

By: Darrel O’Donnell, Jan 2024

§ Questions and usecases

| TBW |

How are the following roles supported (applies to either KERISSE or TEv2)?

1. Authors of technical documents that need to reference glossaries/glossary entries
2. Authors of glossary terms
3. Curators of glossaries (manage changes, toolsets, etc.)
4. Glossary Tech developers
5. Instructors and educators for organizations creating and using glossaries and glossary terms for ToIP-related documentation?

What are the supported source document types for:

1. Documents that reference glossary terms and concepts
2. Authoring terms and related extended definitions, examples, and illustrations (in-depth explanations?)
3. Term/Concept metadata (gdocs? JSON?)

| TBW |

Guidance on diagrams (and managing their source) would be helpful.

For example, should diagrams always be rendered and controlled as png and preferably svg, too (for presentations, etc)?

Is it feasible to offer links in diagrams and if so, can we check and repair broken links easily?

| TBW |

§ Tools landscape

People like to understand the components and structure of ToIP’s concepts and terminology machinery and its governance.

§ git and github

§ Why?

• We need to know who did what
• We need to be able to get back and link to historical (intermediate) result

§ How?

Every role that changes stuff (Create, Update or Delete) needs to be on github and sign off their work

This way:

• original sources are GitHub managed and so is the provenance of each definition
• we can track provenance carefully. This is a step towards fully managed, individually versioned glossary management tooling such as being developed with TEv2 and KERISSE.

§ Github landscape

Every group within ToIP that uses Spec-Up has a setup more or less like the following. Only WOT-terms uses a combination of wiki source management and publication in KERISSE (Still Docusaurus-based, looking into a Spec-Up variant as of Feb 2024).

§ Flow of Writing a Specification in Spec-Up

§ Glossary Flow: Ingest - Curation - Output

By: Darrell O’Donnell, Jan 2024

§ Combining central, external and internal references to definitions

| TBW : ToIP’s position on KERISSE (a superset of terms and concepts documentation) and TEv2? |

ToIP might need both, particularly to onramp organizations leveraging ToIP.

What are the components of the following glossary/term/concept toolsets

• Github (repo, pages and wiki)
• Spec-Up
• KERISSE platform toolset
• TEv2 toolset

What features exist in both, and what is unique in each toolset? If there is overlap, how are they different (e.g., how does an author craft a link from a word in a source document to a term in a specified glossary), and how could they be combined?

What is the future of the KERISSE suite and TEv2?

| TBW |

§ Writing

In case of a specification it is important to ask yourself “Is what I write implementable?” Follow it step by step. Check all the MUSTs and SHOULDs in the normative section.

§ Readability

• numbering of paragraphs
• Informative stuff per section below the normative

§ Review and cooperation

Keep stuff in place where it was/is during the review period. When the review period is over, you could

• relocate sections and paragraphs in the most logical - of best flowing manner
• split the text over markdown files in the spec-up ./spec folder

§ Style guide for ToIP terminology

A term that is intended to be generic SHOULD be lowercase in the glossary and in the specs and other documents that use that term. A term SHOULD only be uppercase if it is a proper noun. The only exception is an acronym. For example, the following terms are all generic nouns:

• wallet
• agent
• public key (and public-key)
• key event log (and key-event-log)

§ Transform spaces to dashes

| TBW : see guideline ToIP by Daniel Hardman for the wiki markdown-files|

§ Forms

Terminology can be defined in various forms: nouns, verbs, adjectives/adverbs, and relations(hips).

§ Example

Noun: Verifier Verb: Verify Adjective: verified (signature) Relationships: verifying

Authors are free to choose any form of a term. It’s a way to express their objectives and concepts and give meaning. Even multiple forms are welcome, which means that in your scope you COULD define the noun, the verb and a relationship. E.g. verifier, verify and veryfying.

§ Acronyms

The following terms are proper nouns or acronyms:

• ToIP
• W3C
• DIF
• X.509
• Diffie-Hellman
• KEL

§ Special characters

Notice that the Acrynom X.509 has a special character (.) You SHOULD use special characters only if it’s crucial for the meaning of the term.

So for example not this: security@hub4issuer but stick to guidelines above and define for example security-at-hub-for-issuer.

§ Constants, variables and terms in coding

Sometimes acronyms in code are (partly) in lowercase (e.g. vLEI, eID, ind) for various reasons. And one needs to explain those acronyms in concepts and terminology, we allow for doing so, in their original case.

§ Authors partly comply and have freedom of choice

§ Comply with

• all of the above-mentioned style guides
• the governance of terms using the current terminolgy source management tools

See the Roles section for the various subroles of an author.

§ Terminology

proper noun

| TBW |

§ Normative references

This section is normative.

The normative section we call the “Spec-Up glossary tool” (SGT); to give a name to the coding project for now.

§ Background

To simplify the job of tech spec construction and editing, the Technology Stack WG has adopted the Spec-Up spec editing tool which is originally a DIF open source project. Spec-Up has been used by TSWG spec authros including Darrell O’Donnell (ToIP Trust Registry Protocol Specification), Drummond Reed (ToIP Technology Architecture Specification), Lance Byrd (did:webs Method Specification) and Henk van Cann (WebofTrust kerific-spec and this Guide). All of them need basic glossary management in these specs. In the ToIP Technology Architecture Specification it’s a long-desired feature to add an integrated glossary.

Spec-Up already has a basic glossary feature: def tags for defining glossary entries and ref tags for marking up terms in the spec that refer to def-tagged terms. As an author there are mainly just two additional features we would need in Spec-Up to have “MVP” glossary management for all the specs coming out of TSWG over the next few months.

§ Feature requests

The first feature is to add Spec-Up code that detects dangling refs and defs. In other words, code that checks to see that: a) any ref tag defined in the spec has a corresponding def tag for the glossary entry, and b) every def tag defining a glossary entry has at least one ref tag pointing to it.

The second feature addresses a current limitation of Spec-Up: ref tags can only reference def tags in the same Spec-Up document. Darrell had the brilliant idea that the CTWG should begin publishing the ToIP Glossary as its own standalone Spec-Up specification, where every entry is properly formatted with a Spec-Up def tag. If we do that, then all we need for any TSWG specification to be able to include terms from the ToIP Glossary (without having to copy those 400+ terms over into its own glossary) is to enhance Spec-Up code to support remote refs.

It should check each def created in a local Spec-Up document against any def that exists in any of the remote ref document URLs listed in the local document (see the “doctag” list description)

When a certain Spec-Up document includes a certain glossary from another Spec-Up document, this is a statement: “we think we might be on the same page as the people that maintain this glossary”. It’s important to realize why somebody in which role

| TBW doctag |

§ Internal definition (def)

definitions (defs)

[[def: term { | abbrev}, {alias}, {alias}, ... ]]
~ Lorem Ipsum ...

A term SHOULD be defined as a ToIP definition style : lower case

An alias COULD be referenced. If you do so the reference MUST end up at the definition of term This is already operational in the current version of Spec-Up and implemented with nested spans

::: ISSUE https://github.com/henkvancann/terminology-governance-guide/issues/1 :::

Check defs of aliases https://github.com/decentralized-identity/spec-up/blob/master/single-file-test/spec.md#term-references and the working refs here https://identity.foundation/spec-up/#term-references

abbrev COULD be defined and referenced. If you do so a seperate definition of abbrev MUST be present in the document itself:

[[def: abbrev]]
~ [the term the abbrev refers to]

Example of the duplet:

[[def: KEL]]
~ [[ref: key event log]]

[[def: key event log | KEL, Key-event log ]]
~ Lorem Ipsum ...

§ Don’t do this

[[def: term (abbrev)]] and  
[[ref: phrase]]

but do this

[[def: term | abbrev]]

How to add an abbreviation after the term? Two ways possible:

1. in the markdown, but NOT in the reference to the term: ref: There will be post-markdown processing available to proportionally add abbreviation

§ Internal linking (ref)

[[ref: phrase]]

phrase MUST be one of term, abbrev or alias

Three ways of offering references (refs) to definitions (defs) by the author of a text:

1. explicitly created by author

2. extra by default, after n occurrences or below a header of certain level

3. MUST be done in the source by hand

4. MUST be done by code, we’ll add a data-attribute to the resulting hrml that indicates the origin of the link.

§ External linking (ref)

We need the capability for all ToIP specs to use remote refs to reference a common ToIP Glossary in addition to their own internal glossary. So far an inventarisation under TSWG spec authors would be fine with that capability: they can use any term already defined in the ToIP Glossary without having to repeat it in their glossary, and they can add any term specific to their spec.

[[ref: group#phrase]]

phrase MUST be one of term in any of group’s glossary.

For example, a specification that includes a ref tag that looks like this: toip#term would reference a def tag defined in the ToIP Glossary. Similarly, a ref that looks like hxwg#term would reference a defined term in the (theoretical) HXWG glossary.

With this remote reference feature, all ToIP specifications (and any other deliverable written with Spec-Up) would be able to include linked glossary terms (including hover pop-up definitions) both from within its own glossary and from any referenced glossary in another document that also uses Spec-Up.

Mind you, this process touches group dynamics, consensus building and communication.

| TBW dangers of bluntly referencing and copying |

Technically, the only difference between a local ref and a remote ref is that the former are always within the same Spec-Up document — they look like:

term

The latter allow the author to reference a def in a different Spec-Up document. They look something like:

doctag#term or term

doctag is a short unique tag assigned to the remote Spec-Up document containing the def for the term being referenced. So any Spec-Up document that uses remote refs would need to include a doctag section that looks something like this:

[[doctags:

[toip:https://trustoverip.github.org/cwtg/toip-glossary.md]

[hxwg:https://trustoverip.github.org/hxwg/hxwg-glossary.md]

]]

| TBW where is the registry to ensure uniqueness of doctags and prevention of duplicious doctags? |

§ System feature Consistency

Consistency and rules for def:s and ref:s leads to github.io page with all kinds of working internal and external links and clear rules for writers.

§ Basic domain checks

1. characterset
2. spaces and | TBW |

§ Domain checks Spe-Up or github actions

1. No abbrevs in the text of a term either in “()” or after “;”
2. The system must warn for double aliases in one def
3. The system must warn for double abbrevs in one def
4. No duplicity in wording in term, abbrev and alias(ses)
5. If term and abbrev are the same, discard abbrev
6. If alias and term are the same, discard alias
7. If abbrev and alias are the same, discard alias

| TBW What is ‘the same’ ? |

§ Parser checks Spe-Up or github actions

1. The system must warn for double aliases in more than one def
2. The system must warn for double abbrevs in more than one def
3. The system must report broken internal links, refs that don’t match term, abbrev nor aliasses.

§ External Consistency

We like reuse of existing terminology, laid out in definitions and glossaries. If applied correctly, reuse will increase consensus within TrustoverIP.

Given this positive effect we encourage people to look what’s there already before defining and writing your own definition.

How do we know which known glossary to use? Maybe any glossary we have previously created a cross reference from should be included? There is already tooling available to include existing glossaries and give a unified overview of them in KERISSE. This listing can be adjusted to “ToIP only”.

§ No effective system without governance

The governance rules that we have to put in place (at least with the ToIP community) should be:

1. If the spec authors want to use a term with its definition term as defined in the ToIP Glossary, the spec authors MUST insert a remote ref to that term in their spec and MUST NOT copy the term (or worse, redefine it) in their internal spec glossary.

2. If the spec authors want to use a term defined in the ToIP Glossary but modify its definition, they COULD submit raise an issue and/or a pull request to the ToIP Glossary making the case for their proposed change. If that change is resolved to their satsifaction, they can proceed as per rule #1 above.

3. If the spec authors want to use a new term that does not exist in the ToIP Glossary to their liking, they have two choices:

• If the spec authors believe the term should apply “ToIP community-wide”, they can submit a PR to have it added to the ToIP Glossary. If accepted, they can then follow rule #1 above.
• If the spec authors believe the term only applies in the scope of their particular spec, they can define it with a def tag in their own internal spec glossary and then ref it there.

Of course, this set of rules only works within an coherent community willing to follow them. We can’t control the use of terminology outside of the ToIP community.

§ System feature functionality

The front-end functionality of the resulting github.io page can and must be altered to comply with various Reader allowances:

• Only so and so often a link to known term in the glossary
• Only so and so often an abbreviation of term added to the term in the core text
• Pop-ups consistenly showing definitions while hovering over the term
• Consensus tooling (kerific) as a browser extension

| TBW |

§ System feature layout

The front-end layout and pdf layout of the resulting github.io page can and must be altered to comply with various style-guide rules of external parties like IETF or ISO.

| TBW |

§ Integration

This is an informative section

Spec-Up, Spec-Up Glossary tool, TEv2 and the KERISSE-engine plus kerific tooling are gradually going to integrated for the sake of concept & terminology management in ToIP.

This section might why we anticipate with this Governance Guide on future development the way we’ve done in the previous sections.

§ Concerns

We share some concern raised over the first months in 2024.

§ Spec-Up and Specification Template

Current copy and paste strategy leading to merge horror “unrelated histories”.

How we should fork to stay in tune with each-other and easily accept improvements?

Noticed the differences?

1. Through forking instead of copying we keep git histories compatible
2. Through fetch+merge (or pull when no conflicts expected) we not only keep DIF and ToIP synced, but also it is very straightforward to update all the gh-pages-based specification websites that use the Specification Template to:
   • sync functionality and data
   • offer PRs from any of those installs

§ Roadmap to TEv2

As a TEv2 creator and frontman we share Rieks Joosten’s viewpoint on this proposal for using Spec-Up refs and defs.

He explained that the same features being discussed here were also added to TEv2.

There is always tension between adding a lot of features and taking a long time, or keeping things very minimal. He pointed out that creating glossaries based on cherry-picking glossary entries based on personal preferences can be problematic because it doesn’t actually establish shared understanding and criteria for defining terms.
The larger the group involved, and the more varied their cultural backgrounds, the more problematic that can become. However, that doesn’t mean we shouldn’t start with tools that are actually working right now. Riek’s personal preference is to use terminology that expresses the author’s intentions clearly. For example, in reading the Spec-Up documentation, it was challenging for Rieks to understand it without more context.

Rieks would like to have several more sessions on TEv2 so we can still look at how we can use it for our terminology. He’s not opposed to enhancing Spec-Up for these features, but at the same time keeping TEv2 tooling in progress.

Rieks Joosten concluded that we need to see what tools are actually needed by both authors and readers to help them comprehend the terms they use. He can also explore how TEv2 tooling can be used to produce Spec-Up definitions.

Rieks Joosten was in favor of proceeding with changes to Spec-Up, but also to continue the work on TEv2 to tackle larger issues of terminology management.

§ TEv2 Explanation

§ Current structure

§ Docusaurus example CURRENT

§ SpecUp example CURRENT

§ Internal Scope

§ External Scopes and internal scope

§ Full architecture

§ Always archive never delete

Darrell O’Donnell clarified that technical maintainers we will not delete any ToIP repos, but will only archive them.

| TBW |

Guide normative~ What is the criterium something being a Guide versus a Specification? A Specification has enough normative statements to be directly implementatable.

normative ~ A theory is “normative” if it, in some sense, tells you what you should do - what action you should take.Also see KERISSE

phrase

Something is a phrase when it’s either a term, an abbreviation or an alias in the context of this guide.

term

The ToIP notation of a terminology item, that requires a definiton, that could have an abbreviation and zero or more aliasses. A term is supposed to be uniquely defined in a certain scope, but can have many exactly the same instances in a broader community.
The term also serves as a key in the source management tool of ToIP terminology sources and to make a comparison among terms.
Criterium: only if a certain word or phrase in ToIP notation and first placed in the definition tag, then it’s a term in the scope of this guide. Only a term can have just one abbreviation.
Also see term.

abbrev

a shorthand in capitals for a term. It may contain special characters. It may not contain spaces.
Criterium for not being an abbreviation: If the word is not in uppercase, in our context the word is more likely to be an alias for the term.

alias

Any notation of a terminology item, that is an alternative for a term being defined. The alias also serves as a comparison among term definitions.
An alias is typically a means to one-on-one relate specific wording to a term already defined. For example :

• Synonyms
• Plural - singular
• Different spelling
• Lowercase versus Uppercase
• another (!) abbreviation Mind you: the most applicable abbreviation should be in abbrev. Criterium: an alias | TBW |

doctag

A short unique tag assigned to the remote Spec-Up document containing the def for the term being referenced. So any Spec-Up document that uses remote refs would need to include a doctag section

§ Annex

§ Comparison Spec-Up 2023 and TEv2 by Rieks Joosten, Jan 2024

This specification has used the following insights to write the Guidelines, most notably in the Roles section and the Normative section.

§ Spec-Up

I have had a look at the latest spec-up draft, specifically that relating to terminology. The text tells you about features it has, but (as often) you need to see the source of that text (in RAW format) to figure out how to do things if you’re new to this. Here’s my understanding: Spec-up term definition syntax is as follows:

<text that is used as the description/definition of ‘term’>

where is the term that is being defined. The documentation doesn’t say what it can(not) be, e.g., whether or not it may contain spaces or special characters, and

appears to be a (single) line of text, which also isn’t further specified.

If you want to specify aliases (what TEv2 calls ‘form phrases’), you say:

<text that is used as the description/definition of ‘term’ (and its aliases)>

where and are as before, and <alias> are the aliases, which are also not further specified, but the example shows they can contain spaces (so the , and the closing ]] are the delimiters for the term list.