diff --git a/spec/16_foreword.md b/spec/16_foreword.md index 8d0c74e..f9a2a92 100644 --- a/spec/16_foreword.md +++ b/spec/16_foreword.md @@ -15,7 +15,7 @@ The mission of the Trust over IP (ToIP) Foundation is to define a complete archi 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. +This document was prepared by the ToIP Concepts and Terminology Working Group. Any feedback or questions on this document should be directed to https://github.com/trustoverip/specification/issues diff --git a/spec/20_introduction.md b/spec/20_introduction.md index 628c887..fd1e664 100644 --- a/spec/20_introduction.md +++ b/spec/20_introduction.md @@ -9,51 +9,10 @@ ## Introduction -The Terminology Governance Guide is up-to-date guide of collected and assimilated expertise within Trust-over-IP with regard to Concepts and Terminology. It's objective is to offer a comprehesive description of various data stores, tools and processes to manage terminology in a consistent and reproducable manner. The process intents to keep track of who did what in which role. -Authors of concepts & terminology use the Guide to produce internally and externally consistent specifications, they could look up how to reference term internally (refer to definitions within the own scope) and externally: refer to definitions externally, either within the own umbrella organisation (ToIP) other totally external (e.g. IETF). -Curators of concepts & terminology have an insight were in the process consistency of terminology is validated by hand or by tools that verify the structure, defs, refs, abbreviation and aliasses that authors might use. +The Terminology Governance Guide is an up-to-date guide of assimilated expertise within Trust-over-IP with regard to Concepts and Terminology. It's objective is to offer a comprehesive description of various data stores, tools and processes to manage terminology in a consistent and reproducable manner. The process intents to keep track of who did what in which role. -There is a brief history to the Guide. In 2021 TrustoverIP published the [Specification for Creating and Using Terms](https://wiki.trustoverip.org/display/HOME/Specification+for+Creating+and+Using+Terms) +*Authors* of concepts & terminology use the Guide to produce internally and externally consistent specifications, they could look up how to reference term internally (refer to definitions within the own scope) and externally: refer to definitions externally, either within the own umbrella organisation (ToIP) other totally external (e.g. IETF). -In the years to follow the guide to create [Term wikis](https://wiki.trustoverip.org/display/HOME/Terms+Wikis) has been established. It gives extensive instructions on how to create wikis, use markdown and hyperlinks, etc. +*Curators* of concepts & terminology have an insight were in the process consistency of terminology is validated by hand or by tools that verify the structure, defs, refs, abbreviation and aliasses that authors might use. -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 - -::: note Basic Note - [Check quickly out](https://henkvancann.github.io/terminology-governance-guide/#system-feature-consistency) how we take on these concerns -::: - -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 *[[ref: 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 - -![Past Practise Terminology Governance](https://github.com/henkvancann/terminology-governance-guide/blob/be980e063e99f97cbb14093735ed42d9e8d617e2/images/past-practice-terminology-gov.png?raw=true) - -### Current Practise Terminology Governance - -![Current Practise Terminology Governance](https://github.com/henkvancann/terminology-governance-guide/blob/be980e063e99f97cbb14093735ed42d9e8d617e2/images/current-practice-terminology-gov.png?raw=true) - -### Future Practise Terminology Governance - -![Future Practise Terminology Governance?](https://github.com/henkvancann/terminology-governance-guide/blob/be980e063e99f97cbb14093735ed42d9e8d617e2/images/future-practice-terminology-gov.png?raw=true) \ No newline at end of file +There is a brief history to the Guide in the [annex](#Annex). diff --git a/spec/24_scope.md b/spec/24_scope.md index 1e20eac..313f8b6 100644 --- a/spec/24_scope.md +++ b/spec/24_scope.md @@ -7,25 +7,21 @@ ## Scope -This Guide goes with the flow as much as it can. This means: +This Guide uses tools currently in use and proven open-source technology as much as possible: + - git and github for version control, issue-handling and project management in the own github repo +- GitHub user management - The existing Slack group CTWG for discussions - Use of github wiki-based source management of terminologies -- Proposal to archive obsolete sources of terminology +- 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 - -![past](https://github.com/henkvancann/terminology-governance-guide/blob/fab622598a0bc03d0fedb62ea989572e082ae6bb/images/Gantt%20Diagram%20temporary%20past.png?raw=true) +How do TEv2, Spec-Up and KERISSE relate? The goal is unification and we prevent reinventing tools that are already in place. -![future](https://github.com/henkvancann/terminology-governance-guide/blob/fab622598a0bc03d0fedb62ea989572e082ae6bb/images/Gantt%20Diagram%20temporary%20future.png?raw=true) +The issue of unification is currently open, but it might be solved with the design of this Guide. A sequence numbered roadmap to unification (presumming that that's the goal) can be found below. +| TBW | \ No newline at end of file diff --git a/spec/32_howto_define.md b/spec/32_howto_define.md index 0ecf030..6e62d3d 100644 --- a/spec/32_howto_define.md +++ b/spec/32_howto_define.md @@ -35,8 +35,10 @@ But unfortunately **not together with referencing existing poorly-formulated def ### Towards automatic processing in github actions +Currently we allow for four types of source management tools of terminologies in ToIP context. +Check them out here: | TBW Link to the chapter |. -Currently github wikis serve as the source management tool of the glossary terms in ToIP context. There are temporary exceptions. +This example uses the github.com wiki of the target repository, but the other source management options could adopt the same guidelines for designing and editing a terminology in ToIP context. Here are a few [practical rules](https://wiki.trustoverip.org/display/HOME/Terms+Wikis) from the originator ToIP to get these wiki terms through their equivalent [github actions script](https://github.com/WebOfTrust/WOT-terms/actions/workflows/content-fetch-and-deploy-update-glossary.yml), please: 1. beware all new wiki items you **create**, lead to new .md files. Because we'd like to know about new definitions, flant them in discussions or social media: throw links! @@ -50,7 +52,9 @@ Here are a few [practical rules](https://wiki.trustoverip.org/display/HOME/Terms _Have fun CRU-ing!_ '* CRU=Create Read Update -### A glossary "reads" this wiki +### A glossary "reads" this + +| TBW this section is draft and incomplete| Where as the wiki source management tool (or *input tool*) of terminology, there is no way to add metadata to the terminology. diff --git a/spec/48_source_management.md b/spec/48_source_management.md index 6636619..32a8f53 100644 --- a/spec/48_source_management.md +++ b/spec/48_source_management.md @@ -2,18 +2,21 @@ ## Source Management Use Cases -Input knowledge level: You know how to create, read and update term definitions in relation to | TBW how to edit a wiki entry | +Input knowledge level: You know how to create, read and update term definitions in relation to your concept or mental model. Here are some guidelines: [edit wiki term definitions](#towards-automatic-processing-in-github-actions) -### What -This section is about the source management of term and definitions: the latest single source of truth about them in a certain scope. The elementary part is {term}.md file that contains (spec-up extended) markdown. We offer various ways of managing these source files with integrity. +### What is this about? +This section is about the source management of term and definitions: the latest single source of truth about them in a certain scope. The elementary part is `{term}.md` file that contains (spec-up extended) markdown. We offer various ways of managing these source files while keeping the overall integrity. ### What can I do with it? -Source management culminates in the *latest version* of any glossary in which the term are accessible (linkable) with a *persistent URL* and we have a *history avaiable* who referered this term at what time in the past. -You can reference this glossary in your own write ups and add to the general consensus about terms at the same time. +Source management culminates in the *latest version* of any glossary in which the term are accessible (linkable) with a *permanent URL* and we have a *history avaiable* who referered this term at what time in the past. -### Why -We want to offer multiple ways to edit term definitions. So not wiki **or** markdown **or** github frontend but wiki **and** markdown **and** github frontend. -The end-result is always a git(hub) tracked directory with separate .md files of a spec-up based specification. The use case are described below. The term definitions themselves use the spec-up markdown extensions syntax: `def`, `ref` and `xref`. +:::info +You can reference this glossary in your own write-ups and add to the general consensus about terms at the same time. +::: + +### Why source management? +We want to offer multiple ways to edit term definitions. So not wiki **or** markdown **or** github frontend but wiki **and** markdown **and** github frontend? +The end-result is always a git(hub) tracked directory with separate `.md` files of a spec-up based specification. The use case are described below. The term definitions themselves use the spec-up markdown extensions syntax: `def`, `ref` and `xref`. Example given: @@ -23,39 +26,38 @@ Example given: and using information and related information [[xref: processing]] services. ``` -### Why not simply a Content Management System like Wordpress??! +### Why not simply use a Content Management System like Wordpress??! +Just to name a few reasons: 1. user management in github ecosystem instead of centralized technological island creation 2. Spec-up static website generation, we don't want introduction of databases 3. Continuous Developement Continuous Integration (CDCI) versus staging by hand 4. Business rules and Permanent linking made possible via Github Actions -Just to name a few reasons. -### Who -The roles involved in the use cases are editor, production repo master and curator. +### For who is source management of terminology relevant? +The roles involved in the use cases are `editor`, `production repo` master and `curator`. One person could have more than one role. -All roles have a github user account, because we need to know +**All roles have a github user account**, because we need to know - *who* proposes a change on *what* and *when* this occurred. - who changes what and when. -Git keeps track. +Git keeps track for us. -He/she who has write user rights on the target repo (TrustoverIP main glossary) can directly edit and commit the latest version. Other roles will have to adapt to those results. For example merge confilcts might arise and need to be solved. +He/she who has `write` user rights on the target repo (TrustoverIP main glossary) can directly edit and commit the latest version. Other roles will have to adapt to those results. For example *merge conflicts* might arise and then need to be solved. Further guidelines: - editors COULD have a fork of the repo. They NEED TO have a forked target repo for option 2, 3 and 4 below. - curators don't need to have a user github repo, only a github user account and they use the functionality to comment on PRs. -### How -Github Actions will pick up and process changes as they occur. +### How it works +Github Actions will pick up and process changes as they occur and trigger staging of chancing to the production server. -This is the process diagram +This is the process diagram: ![Terms-dir-circular](https://github.com/trustoverip/ctwg-terminology-governance-guide/blob/eb572181e2e66fa8453162affa25b86a7c984838/images/Terms-dir-circular.png?raw=true) - -These are the two main options we have use cases for: +There are two main options we have use cases for: - A. Wiki based = edits WITHOUT curation and PR are possible, see 1. below @@ -63,8 +65,11 @@ These are the two main options we have use cases for: ### 1. Wiki -The terms-definitions directory will be exported to a clone of the target repo wiki by the production repo `master`. -The wiki (sub) repo of a github repo allows for different user right settings than the repo itself. +Go to the wiki of your project repo on github.com (which is controlled by master). The wiki offers edit functionality. + +> DEEP DIVE: This is what happens if you can straight away save the wiki pages you edit: +> The terms-definitions directory will be exported to a clone of the target repo wiki by the production repo `master`. +> The wiki (sub) repo of a github repo allows for different user right settings than the repo itself. GitHub allows the master to configure access permissions for wikis independently of the main repository settings. Here's how the permission settings can differ: @@ -73,14 +78,18 @@ By default, a repository's wiki inherits the permissions from the repository its a. Inherit permissions from the repository, meaning those with write access to the repository can edit the wiki. b. Allow everyone with a GitHub account to edit the wiki, which makes the wiki more open, regardless of their access to the repository itself. -This flexibility allows project maintainers to either keep their wikis as collaborative spaces open to the wider GitHub community or restrict them to be consistent with the access controls applied to the source code in the repository. It's worth noting that these settings can be changed at any time by the repository owner or users with admin access to the repository. +This flexibility allows project maintainers to either keep their wikis as collaborative spaces open to the wider GitHub community or restrict them to be consistent with the access controls applied to the source code in the repository. It's worth noting that these settings can be changed at any time by the repository owner (master) or users with admin access to the repository. -Now `editors` can us the wiki of the target repo to CRU term definition. We describe separate use cases for C, R, U. Delete is very rare, because the history of terms should be kept available. +#### CRUD + +Now `editors` can use the wiki of the target repo to CRU term definition. We describe separate use cases for Create, Read and Update (CRU). Delete (D) is very rare, because the history of terms should be kept available. `Curators` could add markdown comments to the sources of the wiki. -> NB: Editing of the target github wiki repo on your local machine is possible but a rather strange way to manage sources of your terms definitions. But it can be done if you have the user rights: push the wiki repo to the target wiki repo. -> We advise to choose one of the other source management options, because it's more direct. +::: note Info Note +NB: Editing of the target github wiki repo on your local machine is possible but a rather strange way to manage sources of your terms definitions. But it can be done if you have the user rights: push the wiki repo to the target wiki repo. +We advise to choose one of the other source management options, because it's more direct. +::: ::: note Basic Note After this source editing has been saved our solution also overwrites the repo file `/spec/splitted-dir/{term}.md` (if present) for syncing purposes. @@ -108,8 +117,11 @@ An integrated Development Environment, e.g. Visual studio Code - text file edit This way editors can edit (after having cloned the target repo to their own user account). He/she uses an IDE to write changes in the separate .md file of the term and definitions directory. He/she uses the IDE git functinality to finally create a PR on the target repo for the curator and the master to assess and eventually accept or decline. After the PR is made the curator can comment on the changes proposed and live viewable on the user account of the editor. -The input is a per-term splitted directory of term md files -The end result is a 4 options to make changes and 2 options to get the results accepted in the target repo and final spec-up html output: Via 1. Wiki and via 2,3,4 : PR. +#### Source management of terminology wrapped up + +**The input** is a per-term splitted directory of term md files +**The process** : four options to make changes +**The end result** two options to get the results accepted in the target repo and final spec-up html output: Via 1. Wiki and via 2,3,4 : PR. All methods have full git tracing of who did what and when. @@ -117,13 +129,13 @@ All methods have full git tracing of who did what and when. After this source editing have been saved our solution also overwrites the wiki repo file `/{term}.md` (if present) for syncing purposes. ::: -### How +### How it works in use cases The rest of this chapter outlines the use cases for managing term definitions in a spec-up based specification, focusing on the roles of editors, production repo masters, and curators. We focus on **terms and definitions only**. We use the term *target repo* for the production repo, controlled by the role `master`. -### Roles +### Roles in the usecases - **Editor**: Individuals proposing changes to term definitions. - **Production Repo Master (Master)**: Oversees the merging of PRs and has the authority to delete term definitions. @@ -145,7 +157,7 @@ We focus on **terms and definitions only**. We use the term *target repo* for th - **Process**: Similar to "Create", but select an existing term's page to edit. ##### Read (R) -- Directly view the term's page in the Wiki section. +- Directly view the term's page in the Wiki section. Mind you, this is an extra view & search option of the resulting glossary. #### 2. GitHub Edit (via GitHub UI) @@ -155,7 +167,7 @@ We focus on **terms and definitions only**. We use the term *target repo* for th 1. Fork the target repository to your GitHub account. 2. In your fork, navigate to the `terms-definitions` directory. 3. To add a new term, click "Add file" > "Create new file". To update, click on an existing `.md` file and then the pencil icon (Edit this file). - 4. Make changes or add the new term using markdown syntax. Commit the changes to a new branch in your fork, and start a pull request. + 4. Make changes or add the new term using markdown syntax. Commit the changes to a new branch in your fork, and start a pull request on the target repo. ##### Read (R) - View the `.md` files directly in the target repository or through the proposed changes in pull requests. @@ -189,7 +201,7 @@ We focus on **terms and definitions only**. We use the term *target repo* for th #### Delete (D) by Master - **Process**: - 1. For deleting a term, remove the `.md` file or edit its content to reflect the term's deprecation, committing with a clear rationale. Only in exceptional cases, because it's far better to archive instead of delete. So also the | LINK guidelines to edit text | + 1. For deleting a term, remove the `.md` file or edit its content to reflect the term's deprecation, committing with a clear rationale. Only in exceptional cases, because it's far better to archive instead of delete. So also [edit wiki term definitions](#towards-automatic-processing-in-github-actions). 2. Push the changes to the main branch and update any documentation accordingly. #### Curator Review diff --git a/spec/annex.md b/spec/annex.md index a66548d..bade08e 100644 --- a/spec/annex.md +++ b/spec/annex.md @@ -11,6 +11,8 @@ ## 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. @@ -80,4 +82,53 @@ When we were talking about the 'term communities', we also had the role of 'cont Apart from having the minimalistic use-cases, I think it would be helpful if, for every activity or product from the CTWG, we know who would *actually* be using it, and what they would need to be able to do with that -so that we can make sure that they can use it and do with it what they need to. And IMHO that is far from trivial, we we should give that some attention. \ No newline at end of file +so that we can make sure that they can use it and do with it what they need to. And IMHO that is far from trivial, we we should give that some attention. + + + +### Brief history to the Guide + +In 2021 TrustoverIP published the [Specification for Creating and Using Terms](https://wiki.trustoverip.org/display/HOME/Specification+for+Creating+and+Using+Terms) + +In the years to follow the guide to create [Term wikis](https://wiki.trustoverip.org/display/HOME/Terms+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 + +::: note Basic Note + [Check quickly out](https://henkvancann.github.io/ctwg-terminology-governance-guide/#system-feature-consistency) how we take on these concerns +::: + +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 *[[ref: 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 + +![Past Practise Terminology Governance](https://github.com/henkvancann/terminology-governance-guide/blob/be980e063e99f97cbb14093735ed42d9e8d617e2/images/past-practice-terminology-gov.png?raw=true) + +### Current Practise Terminology Governance + +![Current Practise Terminology Governance](https://github.com/henkvancann/terminology-governance-guide/blob/be980e063e99f97cbb14093735ed42d9e8d617e2/images/current-practice-terminology-gov.png?raw=true) + +### Future Practise Terminology Governance + +![Future Practise Terminology Governance?](https://github.com/henkvancann/terminology-governance-guide/blob/be980e063e99f97cbb14093735ed42d9e8d617e2/images/future-practice-terminology-gov.png?raw=true) \ No newline at end of file diff --git a/specs.json b/specs.json index e32d2d1..c89e011 100644 --- a/specs.json +++ b/specs.json @@ -23,7 +23,8 @@ "60_terms_and_definitions.md", "64_biblio.md", "68_spec-up-improvements.md", - "72_integration.md" + "72_integration.md", + "90_annex.md" ], "logo": "https://raw.githubusercontent.com/trustoverip/logo-assets/master/logos/ToIP-Logo-Color-SolidDimensional-Horizontal-LightOnDark.svg", "logo_link": "https://github.com/trustoverip/specification-template",